quickjs

package module
v0.1.3 Latest Latest
Warning

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

 Go to latest Published: Jul 26, 2022 License: MIT Imports: 8 Imported by: 22

README

quickjs-go

Test codecov Go Report Card GoDoc FOSSA Status

Go bindings to QuickJS: a fast, small, and embeddable ES2020 JavaScript interpreter.

Features

  • Evaluate script
  • Compile script into bytecode and Eval from bytecode
  • Operate JavaScript values and objects in Go
  • Bind Go function to JavaScript async/sync function
  • Simple exception throwing and catching

Guidelines

  1. Free quickjs.Runtime and quickjs.Context once you are done using them.
  2. Free quickjs.Value's returned by Eval() and EvalFile(). All other values do not need to be freed, as they get garbage-collected.
  3. You may access the stacktrace of an error returned by Eval() or EvalFile() by casting it to a *quickjs.Error.
  4. Make new copies of arguments should you want to return them in functions you created.
  5. Make sure to call runtime.LockOSThread() to ensure that QuickJS always operates in the exact same thread.

Usage

import "github.com/buke/quickjs-go"
Run a script
package main

import (
	"fmt"
    
	"github.com/buke/quickjs-go"
)

func main() {
    // Create a new runtime
    rt := quickjs.NewRuntime()
    defer rt.Close()

    // Create a new context
    ctx := rt.NewContext()
    defer ctx.Close()

    ret, err := ctx.Eval("'Hello ' + 'QuickJS!'")
    if err != nil {
        println(err.Error())
    }
    fmt.Println(ret.String())
}
Get/Set Javascript Object
package main

import (
	"fmt"
    
	"github.com/buke/quickjs-go"
)

func main() {
    // Create a new runtime
    rt := quickjs.NewRuntime()
    defer rt.Close()

    // Create a new context
    ctx := rt.NewContext()
    defer ctx.Close()

    test := ctx.Object()
    test.Set("A", ctx.String("String A"))
    test.Set("B", ctx.String("String B"))
    test.Set("C", ctx.String("String C"))
    ctx.Globals().Set("test", test)

    ret, _ := ctx.Eval(`Object.keys(test).map(key => test[key]).join(" ")`)
    defer ret.Free()
    fmt.Println(ret.String())
}
Bind Go Funtion to Javascript async/sync function
package main
import "github.com/buke/quickjs-go"

func main() {
    // Create a new runtime
	rt := quickjs.NewRuntime()
	defer rt.Close()

	// Create a new context
	ctx := rt.NewContext()
	defer ctx.Close()

	// Create a new object
	test := ctx.Object()
	defer test.Free()
	// bind properties to the object
	test.Set("A", test.Context().String("String A"))
	test.Set("B", ctx.Int32(0))
	test.Set("C", ctx.Bool(false))
	// bind go function to js object
	test.Set("hello", ctx.Function(func(ctx *quickjs.Context, this quickjs.Value, args []quickjs.Value) quickjs.Value {
		return ctx.String("Hello " + args[0].String())
	}))

	// bind "test" object to global object
	ctx.Globals().Set("test", test)

	// call js function by js
	js_ret, _ := ctx.Eval(`test.hello("Javascript!")`)
	fmt.Println(js_ret.String())

	// call js function by go
	go_ret := ctx.Globals().Get("test").Call("hello", ctx.String("Golang!"))
	fmt.Println(go_ret.String())

	//bind go function to Javascript async function
	ctx.Globals().Set("testAsync", ctx.AsyncFunction(func(ctx *quickjs.Context, this quickjs.Value, promise quickjs.Value, args []quickjs.Value) {
		promise.Call("resolve", ctx.String("Hello Async Function!"))
	}))

	ret, _ := ctx.Eval(`
			var ret;
			testAsync().then(v => ret = v)
		`)
	defer ret.Free()

    // wait for promise to resolve
	for {
		_, err := rt.ExecutePendingJob()
		if err == io.EOF {
			err = nil
			break
		}
	}
    //get promise result
	asyncRet, _ := ctx.Eval("ret")
	defer asyncRet.Free()

	fmt.Println(asyncRet.String())

	// Output:
	// Hello Javascript!
	// Hello Golang!
	// Hello Async Function!
}
Error Handling
package main

import (
	"fmt"
    
	"github.com/buke/quickjs-go"
)

func main() {
    // Create a new runtime
    rt := quickjs.NewRuntime()
    defer rt.Close()

    // Create a new context
    ctx := rt.NewContext()
    defer ctx.Close()

    ctx.Globals().SetFunction("A", func(ctx *Context, this Value, args []Value) Value {
        // raise error
        return ctx.ThrowError(expected)
    })

    _, actual := ctx.Eval("A()")
    fmt.Println(actual.Error())
}
Bytecode Compiler

package main

import (
	"fmt"
    
	"github.com/buke/quickjs-go"
)

func main() {
    // Create a new runtime
    rt := quickjs.NewRuntime()
    defer rt.Close()
    // Create a new context
    ctx := rt.NewContext()
    defer ctx.Close()

    jsStr := `
    function fib(n)
    {
        if (n <= 0)
            return 0;
        else if (n == 1)
            return 1;
        else
            return fib(n - 1) + fib(n - 2);
    }
    fib(10)
    `
    // Compile the script to bytecode
    buf, _ := ctx.Compile(jsStr)

    // Create a new runtime 
    rt2 := quickjs.NewRuntime()
    defer rt2.Close()

    // Create a new context
    ctx2 := rt2.NewContext()
    defer ctx2.Close()

    //Eval bytecode
    result, _ := ctx2.EvalBytecode(buf)
    fmt.Println(result.Int32())
}
Runtime Options: memory, stack, GC, ...
package main

import (
	"fmt"
    
	"github.com/buke/quickjs-go"
)

func main() {
    // Create a new runtime
    rt := quickjs.NewRuntime()
    defer rt.Close()

    // set runtime options
    rt.SetMemoryLimit(256 * 1024) //256KB
    rt.SetMaxStackSize(65534)

    // Create a new context
    ctx := rt.NewContext()
    defer ctx.Close()

    result, err := ctx.Eval(`var array = []; while (true) { array.push(null) }`)
    defer result.Free()
}

Documentation

Go Reference & more examples: https://pkg.go.dev/github.com/buke/quickjs-go

License

MIT

FOSSA Status

Documentation

Overview

Package quickjs Go bindings to QuickJS: a fast, small, and embeddable ES2020 JavaScript interpreter

Example 
// Create a new runtime
rt := quickjs.NewRuntime()
defer rt.Close()

// Create a new context
ctx := rt.NewContext()
defer ctx.Close()

// Create a new object
test := ctx.Object()
defer test.Free()
// bind properties to the object
test.Set("A", test.Context().String("String A"))
test.Set("B", ctx.Int32(0))
test.Set("C", ctx.Bool(false))
// bind go function to js object
test.Set("hello", ctx.Function(func(ctx *quickjs.Context, this quickjs.Value, args []quickjs.Value) quickjs.Value {
	return ctx.String("Hello " + args[0].String())
}))

// bind "test" object to global object
ctx.Globals().Set("test", test)

// call js function by js
js_ret, _ := ctx.Eval(`test.hello("Javascript!")`)
fmt.Println(js_ret.String())

// call js function by go
go_ret := ctx.Globals().Get("test").Call("hello", ctx.String("Golang!"))
fmt.Println(go_ret.String())

//bind go function to Javascript async function
ctx.Globals().Set("testAsync", ctx.AsyncFunction(func(ctx *quickjs.Context, this quickjs.Value, promise quickjs.Value, args []quickjs.Value) quickjs.Value {
	return promise.Call("resolve", ctx.String("Hello Async Function!"))
}))

ret, _ := ctx.Eval(`
			var ret;
			testAsync().then(v => ret = v)
		`)
defer ret.Free()

for {
	_, err := rt.ExecutePendingJob()
	if err == io.EOF {
		err = nil
		break
	}
}
asyncRet, _ := ctx.Eval("ret")
defer asyncRet.Free()

fmt.Println(asyncRet.String())

Output:

Hello Javascript!
Hello Golang!
Hello Async Function!

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Atom 

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

Object property names and some strings are stored as Atoms (unique strings) to save memory and allow fast comparison. Atoms are represented as a 32 bit integer. Half of the atom range is reserved for immediate integer literals from 0 to 2^{31}-1.

func (Atom) Free 

func (a Atom) Free()

Free the value.

func (Atom) String 

func (a Atom) String() string

String returns the string representation of the value.

func (Atom) Value 

func (a Atom) Value() Value

Value returns the value of the Atom object.

type Context 

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

Context represents a Javascript context (or Realm). Each JSContext has its own global objects and system objects. There can be several JSContexts per JSRuntime and they can share objects, similar to frames of the same origin sharing Javascript objects in a web browser.

func (*Context) Array 

func (ctx *Context) Array() Value

Array returns a new array value.

func (*Context) AsyncFunction added in v0.1.2 

func (ctx *Context) AsyncFunction(asyncFn func(ctx *Context, this Value, promise Value, args []Value) Value) Value

AsyncFunction returns a js async function value with given function template.

func (*Context) Atom 

func (ctx *Context) Atom(v string) Atom

Atom returns a new Atom value with given string.

func (*Context) AtomIdx 

func (ctx *Context) AtomIdx(idx int64) Atom

Atom returns a new Atom value with given idx.

func (*Context) BigInt64 

func (ctx *Context) BigInt64(v int64) Value

BigInt64 returns a int64 value with given uint64.

func (*Context) BigUint64 

func (ctx *Context) BigUint64(v uint64) Value

BigUint64 returns a uint64 value with given uint64.

func (*Context) Bool 

func (ctx *Context) Bool(b bool) Value

Bool returns a bool value with given bool.

func (*Context) Close 

func (ctx *Context) Close()

Free will free context and all associated objects.

func (*Context) Compile 

func (ctx *Context) Compile(code string) ([]byte, error)

Compile returns a compiled bytecode with given code.

func (*Context) CompileFile 

func (ctx *Context) CompileFile(code, filename string) ([]byte, error)

Compile returns a compiled bytecode with given filename.

func (*Context) Error 

func (ctx *Context) Error(err error) Value

Error returns a new exception value with given message.

func (*Context) Eval 

func (ctx *Context) Eval(code string) (Value, error)

Eval returns a js value with given code. Need call Free() `quickjs.Value`'s returned by `Eval()` and `EvalFile()` and `EvalBytecode()`.

func (*Context) EvalBytecode 

func (ctx *Context) EvalBytecode(buf []byte) (Value, error)

EvalBytecode returns a js value with given bytecode. Need call Free() `quickjs.Value`'s returned by `Eval()` and `EvalFile()` and `EvalBytecode()`.

func (*Context) EvalFile 

func (ctx *Context) EvalFile(code, filename string) (Value, error)

EvalFile returns a js value with given code and filename. Need call Free() `quickjs.Value`'s returned by `Eval()` and `EvalFile()` and `EvalBytecode()`.

func (*Context) Exception 

func (ctx *Context) Exception() error

Exception returns a context's exception value.

func (*Context) Float64 

func (ctx *Context) Float64(v float64) Value

Float64 returns a float64 value with given float64.

func (*Context) Function 

func (ctx *Context) Function(fn func(ctx *Context, this Value, args []Value) Value) Value

Function returns a js function value with given function template.

func (*Context) Globals 

func (ctx *Context) Globals() Value

Global returns a context's global object.

func (*Context) Int32 

func (ctx *Context) Int32(v int32) Value

Int32 returns a int32 value with given int32.

func (*Context) Int64 

func (ctx *Context) Int64(v int64) Value

Int64 returns a int64 value with given int64.

func (*Context) Invoke added in v0.1.3 

func (ctx *Context) Invoke(fn Value, this Value, args ...Value) (Value, error)

Invoke invokes a function with given this value and arguments.

func (*Context) Null 

func (ctx *Context) Null() Value

Null return a null value.

func (*Context) Object 

func (ctx *Context) Object() Value

Object returns a new object value.

func (*Context) String 

func (ctx *Context) String(v string) Value

String returns a string value with given string.

func (*Context) Throw 

func (ctx *Context) Throw(v Value) Value

Throw returns a context's exception value.

func (*Context) ThrowError 

func (ctx *Context) ThrowError(err error) Value

ThrowError returns a context's exception value with given error message.

func (*Context) ThrowInternalError 

func (ctx *Context) ThrowInternalError(format string, args ...interface{}) Value

ThrowInternalError returns a context's exception value with given error message.

func (*Context) ThrowRangeError 

func (ctx *Context) ThrowRangeError(format string, args ...interface{}) Value

ThrowRangeError returns a context's exception value with given error message.

func (*Context) ThrowReferenceError 

func (ctx *Context) ThrowReferenceError(format string, args ...interface{}) Value

ThrowReferenceError returns a context's exception value with given error message.

func (*Context) ThrowSyntaxError 

func (ctx *Context) ThrowSyntaxError(format string, args ...interface{}) Value

ThrowSyntaxError returns a context's exception value with given error message.

func (*Context) ThrowTypeError 

func (ctx *Context) ThrowTypeError(format string, args ...interface{}) Value

ThrowTypeError returns a context's exception value with given error message.

func (*Context) Uint32 

func (ctx *Context) Uint32(v uint32) Value

Uint32 returns a uint32 value with given uint32.

func (*Context) Undefined 

func (ctx *Context) Undefined() Value

Undefined return a undefined value.

func (*Context) Uninitialized 

func (ctx *Context) Uninitialized() Value

Uninitialized returns a uninitialized value.

type Error 

type Error struct {
	Cause string
	Stack string
}

func (Error) Error 

func (err Error) Error() string

type Runtime 

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

Runtime represents a Javascript runtime corresponding to an object heap. Several runtimes can exist at the same time but they cannot exchange objects. Inside a given runtime, no multi-threading is supported.

func NewRuntime 

func NewRuntime() Runtime

NewRuntime creates a new quickjs runtime.

func (Runtime) Close 

func (r Runtime) Close()

Close will free the runtime pointer.

func (Runtime) ExecutePendingJob added in v0.1.1 

func (r Runtime) ExecutePendingJob() (Context, error)

ExecutePendingJob will execute all pending jobs.

func (Runtime) NewContext 

func (r Runtime) NewContext() *Context

NewContext creates a new JavaScript context. enable BigFloat/BigDecimal support and enable . enable operator overloading.

func (Runtime) RunGC 

func (r Runtime) RunGC()

RunGC will call quickjs's garbage collector.

func (Runtime) SetGCThreshold 

func (r Runtime) SetGCThreshold(threshold int64)

SetGCThreshold the runtime's GC threshold; use -1 to disable automatic GC.

func (Runtime) SetMaxStackSize 

func (r Runtime) SetMaxStackSize(stack_size uint32)

SetMaxStackSize will set max runtime's stack size; default is 255

func (Runtime) SetMemoryLimit 

func (r Runtime) SetMemoryLimit(limit uint32)

SetMemoryLimit the runtime memory limit; if not set, it will be unlimit.

type Value 

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

JSValue represents a Javascript value which can be a primitive type or an object. Reference counting is used, so it is important to explicitly duplicate (JS_DupValue(), increment the reference count) or free (JS_FreeValue(), decrement the reference count) JSValues.

func (Value) BigFloat 

func (v Value) BigFloat() *big.Float

BigFloat returns the big.Float value of the value.

func (Value) BigInt 

func (v Value) BigInt() *big.Int

BigInt returns the big.Int value of the value.

func (Value) Bool 

func (v Value) Bool() bool

Bool returns the boolean value of the value.

func (Value) Call 

func (v Value) Call(fname string, args ...Value) Value

Call calls the function with the given arguments.

func (Value) Context 

func (v Value) Context() *Context

Context represents a Javascript context.

func (Value) Delete 

func (v Value) Delete(name string) bool

Delete deletes the property with the given name.

func (Value) DeleteIdx 

func (v Value) DeleteIdx(idx int64) bool

DeleteIdx deletes the property with the given index.

func (Value) Error 

func (v Value) Error() error

Error returns the error value of the value.

func (Value) Float64 

func (v Value) Float64() float64

Float64 returns the float64 value of the value.

func (Value) Free 

func (v Value) Free()

Free the value.

func (Value) Get 

func (v Value) Get(name string) Value

Get returns the value of the property with the given name.

func (Value) GetIdx 

func (v Value) GetIdx(idx int64) Value

GetIdx returns the value of the property with the given index.

func (Value) Has 

func (v Value) Has(name string) bool

Has returns true if the value has the property with the given name.

func (Value) HasIdx 

func (v Value) HasIdx(idx int64) bool

HasIdx returns true if the value has the property with the given index.

func (Value) Int32 

func (v Value) Int32() int32

Int32 returns the int32 value of the value.

func (Value) Int64 

func (v Value) Int64() int64

Int64 returns the int64 value of the value.

func (Value) IsArray 

func (v Value) IsArray() bool

func (Value) IsBigDecimal 

func (v Value) IsBigDecimal() bool

func (Value) IsBigFloat 

func (v Value) IsBigFloat() bool

func (Value) IsBigInt 

func (v Value) IsBigInt() bool

func (Value) IsBool 

func (v Value) IsBool() bool

func (Value) IsError 

func (v Value) IsError() bool

func (Value) IsException 

func (v Value) IsException() bool

func (Value) IsFunction 

func (v Value) IsFunction() bool

func (Value) IsNull 

func (v Value) IsNull() bool

func (Value) IsNumber 

func (v Value) IsNumber() bool

func (Value) IsObject 

func (v Value) IsObject() bool

func (Value) IsString 

func (v Value) IsString() bool

func (Value) IsSymbol 

func (v Value) IsSymbol() bool

func (Value) IsUndefined 

func (v Value) IsUndefined() bool

func (Value) IsUninitialized 

func (v Value) IsUninitialized() bool

func (Value) Len 

func (v Value) Len() int64

Len returns the length of the array.

func (Value) PropertyNames 

func (v Value) PropertyNames() ([]string, error)

PropertyNames returns the names of the properties of the value.

func (Value) Set 

func (v Value) Set(name string, val Value)

Set sets the value of the property with the given name.

func (Value) SetIdx 

func (v Value) SetIdx(idx int64, val Value)

SetIdx sets the value of the property with the given index.

func (Value) String 

func (v Value) String() string

String returns the string representation of the value.

func (Value) Uint32 

func (v Value) Uint32() uint32

Uint32 returns the uint32 value of the value.

Source Files

View all Source files

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.