quickjs

package module
v0.4.3 Latest Latest
Warning

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

 Go to latest Published: Mar 28, 2024 License: MIT Imports: 7 Imported by: 8

README

quickjs-go

English | 简体中文

Test codecov Go Report Card GoDoc FOSSA Status

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

Version Support

quickjs-go QuickJS
v0.1.x v2021-03-27
v0.2.x v2023-12-09
v0.3.x v2024-01-13
v0.4.x v2024-02-14

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. Use ctx.Loop() wait for promise/job result after you using promise/job
  4. You may access the stacktrace of an error returned by Eval() or EvalFile() by casting it to a *quickjs.Error.
  5. Make new copies of arguments should you want to return them in functions you created.

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 resolve
    ctx.Loop()

    //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()

// wait for promise resolve
ctx.Loop()

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 Array added in v0.1.13 

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

func NewQjsArray added in v0.1.13 

func NewQjsArray(value Value, ctx *Context) *Array

func (Array) Delete added in v0.1.13 

func (a Array) Delete(index int64) (bool, error)

func (Array) Free added in v0.1.13 

func (a Array) Free()

func (Array) Get added in v0.1.13 

func (a Array) Get(index int64) (Value, error)

Get 

@Description: get the specific value by subscript
@receiver a :
@param index :
@return Value

func (Array) HasIdx added in v0.1.13 

func (a Array) HasIdx(i int64) bool

HasIdx 

@Description: Determine whether there is data at the current subscript position
@receiver a :
@param i :
@return bool

func (Array) Len added in v0.1.13 

func (a Array) Len() int64

Len 

@Description: get the length of the array
@receiver a :
@return int64

func (Array) Push added in v0.1.13 

func (a Array) Push(elements ...Value) int64

Push 

@Description: add one or more elements after the array,returns the new array length
@receiver a :
@param elements :
@return int64

func (Array) Set added in v0.1.13 

func (a Array) Set(index int64, value Value) error

Set 

@Description:
@receiver a :
@param index :
@param value :
@return error

func (Array) ToValue added in v0.1.13 

func (a Array) ToValue() Value

ToValue 

@Description: get the value object of qjs
@receiver a :
@return Value

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() *Array

Array returns a new array value.

func (*Context) ArrayBuffer added in v0.1.13 

func (ctx *Context) ArrayBuffer(binaryData []byte) Value

ArrayBuffer returns a string value with given binary data.

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

Invoke invokes a function with given this value and arguments.

func (*Context) Loop added in v0.3.3 

func (ctx *Context) Loop()

Loop runs the context's event loop.

func (*Context) Map added in v0.1.13 

func (ctx *Context) Map() *Map

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) ParseJSON added in v0.1.11 

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

ParseJson parses given json string and returns a object value.

func (*Context) Set added in v0.1.13 

func (ctx *Context) Set() *Set

func (*Context) SetInterruptHandler added in v0.1.14 

func (ctx *Context) SetInterruptHandler(handler InterruptHandler)

SetInterruptHandler sets a interrupt handler.

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 InterruptHandler added in v0.1.14 

type InterruptHandler func() int

InterruptHandler is a function type for interrupt handler. 

return != 0 if the JS code needs to be interrupted

type Map added in v0.1.13 

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

func NewQjsMap added in v0.1.13 

func NewQjsMap(value Value, ctx *Context) *Map

func (Map) Call added in v0.1.13 

func (m Map) Call(funcName string, values []Value) Value

Call 

@Description: call some internal methods of js
@receiver a :
@param funcName :
@param values :
@return Value

func (Map) Delete added in v0.1.13 

func (m Map) Delete(key Value)

Delete 

@Description:delete the value of an element by key
@receiver m :
@param key :

func (Map) ForEach added in v0.1.13 

func (m Map) ForEach(forFn func(key Value, value Value))

ForEach 

@Description: iterate map
@receiver m :

func (Map) Free added in v0.1.13 

func (m Map) Free()

func (Map) Get added in v0.1.13 

func (m Map) Get(key Value) Value

Get 

@Description: get the value by key
@receiver m :
@param key :
@return Value

func (Map) Has added in v0.1.13 

func (m Map) Has(key Value) bool

Has 

@Description:determine whether an element exists
@receiver m :
@param key :

func (Map) Put added in v0.1.13 

func (m Map) Put(key Value, value Value)

Put 

@Description:
@receiver m :
@param key :
@param value :

func (Map) ToValue added in v0.1.13 

func (m Map) ToValue() Value

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) 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 Set added in v0.1.13 

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

func NewQjsSet added in v0.1.13 

func NewQjsSet(value Value, ctx *Context) *Set

func (Set) Add added in v0.1.13 

func (s Set) Add(value Value)

Add 

@Description: add element
@receiver s :
@param value :

func (Set) Delete added in v0.1.13 

func (s Set) Delete(value Value)

Delete 

@Description: add element
@receiver s :
@param value :

func (Set) ForEach added in v0.1.13 

func (s Set) ForEach(forFn func(value Value))

ForEach 

@Description: iterate set
@receiver m :

func (Set) Free added in v0.1.13 

func (s Set) Free()

func (Set) Has added in v0.1.13 

func (s Set) Has(value Value) bool

Has 

@Description: determine whether an element exists in the set
@receiver s :
@param value :
@return bool

func (Set) ToValue added in v0.1.13 

func (s Set) ToValue() Value

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) ByteLen added in v0.1.13 

func (v Value) ByteLen() int64

ByteLen returns the length of the ArrayBuffer.

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) IsByteArray added in v0.1.13 

func (v Value) IsByteArray() bool

IsByteArray return true if the value is array buffer

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) IsMap added in v0.1.13 

func (v Value) IsMap() bool

IsMap return true if the value is a map

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) IsSet added in v0.1.13 

func (v Value) IsSet() bool

IsSet return true if the value is a set

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) JSONStringify added in v0.1.11 

func (v Value) JSONStringify() string

JSONString returns the JSON string representation of the value.

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) ToArray added in v0.1.13 

func (v Value) ToArray() *Array

ToArray 

@Description: return array object
@receiver v :
@return *Array

func (Value) ToByteArray added in v0.1.13 

func (v Value) ToByteArray(size uint) ([]byte, error)

func (Value) ToMap added in v0.1.13 

func (v Value) ToMap() *Map

ToMap 

@Description: return map object
@receiver v :
@return *Map

func (Value) ToSet added in v0.1.13 

func (v Value) ToSet() *Set

ToSet 

@Description: return set object
@receiver v :
@return *Set

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.