goja

package module
v0.0.0-...-1321911 Latest Latest
Warning

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

Go to latest
Published: Sep 19, 2020 License: MIT Imports: 34 Imported by: 0

README

goja

ECMAScript 5.1(+) implementation in Go.

GoDoc

Goja is an implementation of ECMAScript 5.1 in pure Go with emphasis on standard compliance and performance.

This project was largely inspired by otto.

Minimum required Go version is 1.14.

Features

Known incompatibilities and caveats

WeakMap

WeakMap maintains "hard" references to its values. This means if a value references a key in a WeakMap or a WeakMap itself, it will not be garbage-collected until the WeakMap becomes unreferenced. To illustrate this:

var m = new WeakMap();
var key = {};
m.set(key, {key: key});
// or m.set(key, key);
key = undefined; // The value will NOT become garbage-collectable at this point
m = undefined; // But it will at this point.

Note, this does not have any effect on the application logic, but causes a higher-than-expected memory usage.

FAQ

How fast is it?

Although it's faster than many scripting language implementations in Go I have seen (for example it's 6-7 times faster than otto on average) it is not a replacement for V8 or SpiderMonkey or any other general-purpose JavaScript engine. You can find some benchmarks here.

Why would I want to use it over a V8 wrapper?

It greatly depends on your usage scenario. If most of the work is done in javascript (for example crypto or any other heavy calculations) you are definitely better off with V8.

If you need a scripting language that drives an engine written in Go so that you need to make frequent calls between Go and javascript passing complex data structures then the cgo overhead may outweigh the benefits of having a faster javascript engine.

Because it's written in pure Go there are no cgo dependencies, it's very easy to build and it should run on any platform supported by Go.

It gives you a much better control over execution environment so can be useful for research.

Is it goroutine-safe?

No. An instance of goja.Runtime can only be used by a single goroutine at a time. You can create as many instances of Runtime as you like but it's not possible to pass object values between runtimes.

Where is setTimeout()?

setTimeout() assumes concurrent execution of code which requires an execution environment, for example an event loop similar to nodejs or a browser. There is a separate project aimed at providing some NodeJS functionality, and it includes an event loop.

Can you implement (feature X from ES6 or higher)?

Some ES6 functionality has been implemented. So far this is mostly built-ins, not syntax enhancements. See https://github.com/dop251/goja/milestone/1 for more details.

The ongoing work is done in the es6 branch which is merged into master when appropriate. Every commit in this branch represents a relatively stable state (i.e. it compiles and passes all enabled tc39 tests), however because the version of tc39 tests I use is quite old, it may be not as well tested as the ES5.1 functionality. Because ES6 is a superset of ES5.1 it should not break your existing code.

I will be adding features in their dependency order and as quickly as my time allows. Please do not ask for ETAs. Features that are open in the milestone are either in progress or will be worked on next.

How do I contribute?

Before submitting a pull request please make sure that:

  • You followed ECMA standard as close as possible. If adding a new feature make sure you've read the specification, do not just base it on a couple of examples that work fine.
  • Your change does not have a significant negative impact on performance (unless it's a bugfix and it's unavoidable)
  • It passes all relevant tc39 tests.

Current Status

  • There should be no breaking changes in the API, however it may be extended.
  • Some of the AnnexB functionality is missing.

Basic Example

vm := goja.New()
v, err := vm.RunString("2 + 2")
if err != nil {
    panic(err)
}
if num := v.Export().(int64); num != 4 {
    panic(num)
}

Passing Values to JS

Any Go value can be passed to JS using Runtime.ToValue() method. See the method's documentation for more details.

Exporting Values from JS

A JS value can be exported into its default Go representation using Value.Export() method.

Alternatively it can be exported into a specific Go variable using Runtime.ExportTo() method.

Within a single export operation the same Object will be represented by the same Go value (either the same map, slice or a pointer to the same struct). This includes circular objects and makes it possible to export them.

Calling JS functions from Go

There are 2 approaches:

vm := New()
_, err := vm.RunString(`
function sum(a, b) {
    return a+b;
}
`)
if err != nil {
    panic(err)
}
sum, ok := AssertFunction(vm.Get("sum"))
if !ok {
    panic("Not a function")
}

res, err := sum(Undefined(), vm.ToValue(40), vm.ToValue(2))
if err != nil {
    panic(err)
}
fmt.Println(res)
// Output: 42
const SCRIPT = `
function f(param) {
    return +param + 2;
}
`

vm := New()
_, err := vm.RunString(SCRIPT)
if err != nil {
    panic(err)
}

var fn func(string) string
err = vm.ExportTo(vm.Get("f"), &fn)
if err != nil {
    panic(err)
}

fmt.Println(fn("40")) // note, _this_ value in the function will be undefined.
// Output: 42

The first one is more low level and allows specifying this value, whereas the second one makes the function look like a normal Go function.

Mapping struct field and method names

By default, the names are passed through as is which means they are capitalised. This does not match the standard JavaScript naming convention, so if you need to make your JS code look more natural or if you are dealing with a 3rd party library, you can use a FieldNameMapper:

vm := New()
vm.SetFieldNameMapper(TagFieldNameMapper("json", true))
type S struct {
    Field int `json:"field"`
}
vm.Set("s", S{Field: 42})
res, _ := vm.RunString(`s.field`) // without the mapper it would have been s.Field
fmt.Println(res.Export())
// Output: 42

There are two standard mappers: TagFieldNameMapper and UncapFieldNameMapper, or you can use your own implementation.

Native Constructors

In order to implement a constructor function in Go:

func MyObject(call goja.ConstructorCall) *Object {
    // call.This contains the newly created object as per http://www.ecma-international.org/ecma-262/5.1/index.html#sec-13.2.2
    // call.Arguments contain arguments passed to the function

    call.This.Set("method", method)

    //...

    // If return value is a non-nil *Object, it will be used instead of call.This
    // This way it is possible to return a Go struct or a map converted
    // into goja.Value using runtime.ToValue(), however in this case
    // instanceof will not work as expected.
    return nil
}

runtime.Set("MyObject", MyObject)

Then it can be used in JS as follows:

var o = new MyObject(arg);
var o1 = MyObject(arg); // same thing
o instanceof MyObject && o1 instanceof MyObject; // true

Regular Expressions

Goja uses the embedded Go regexp library where possible, otherwise it falls back to regexp2.

Exceptions

Any exception thrown in JavaScript is returned as an error of type *Exception. It is possible to extract the value thrown by using the Value() method:

vm := New()
_, err := vm.RunString(`

throw("Test");

`)

if jserr, ok := err.(*Exception); ok {
    if jserr.Value().Export() != "Test" {
        panic("wrong value")
    }
} else {
    panic("wrong type")
}

If a native Go function panics with a Value, it is thrown as a Javascript exception (and therefore can be caught):

var vm *Runtime

func Test() {
    panic(vm.ToValue("Error"))
}

vm = New()
vm.Set("Test", Test)
_, err := vm.RunString(`

try {
    Test();
} catch(e) {
    if (e !== "Error") {
        throw e;
    }
}

`)

if err != nil {
    panic(err)
}

Interrupting

func TestInterrupt(t *testing.T) {
    const SCRIPT = `
    var i = 0;
    for (;;) {
        i++;
    }
    `

    vm := New()
    time.AfterFunc(200 * time.Millisecond, func() {
        vm.Interrupt("halt")
    })

    _, err := vm.RunString(SCRIPT)
    if err == nil {
        t.Fatal("Err is nil")
    }
    // err is of type *InterruptError and its Value() method returns whatever has been passed to vm.Interrupt()
}

NodeJS Compatibility

There is a separate project aimed at providing some of the NodeJS functionality.

Documentation

Index

Examples

Constants

This section is empty.

Variables

View Source
var (
	InvalidRuneError = errors.New("invalid rune")
)

Functions

func IsInfinity

func IsInfinity(v Value) bool

IsInfinity returns true if the supplied is (+/-)Infinity

func IsNaN

func IsNaN(v Value) bool

IsNaN returns true if the supplied value is NaN.

func IsNull

func IsNull(v Value) bool

IsNull returns true if the supplied Value is null.

func IsUndefined

func IsUndefined(v Value) bool

IsUndefined returns true if the supplied Value is undefined. Note, it checks against the real undefined, not against the global object's 'undefined' property.

Types

type ArrayBuffer

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

ArrayBuffer is a Go wrapper around ECMAScript ArrayBuffer. Calling Runtime.ToValue() on it returns the underlying ArrayBuffer. Calling Export() on an ECMAScript ArrayBuffer returns a wrapper. Use Runtime.NewArrayBuffer([]byte) to create one.

func (ArrayBuffer) Bytes

func (a ArrayBuffer) Bytes() []byte

Bytes returns the underlying []byte for this ArrayBuffer. For detached ArrayBuffers returns nil.

func (ArrayBuffer) Detach

func (a ArrayBuffer) Detach() bool

Detach the ArrayBuffer. After this, the underlying []byte becomes unreferenced and any attempt to use this ArrayBuffer results in a TypeError. Returns false if it was already detached, true otherwise. Note, this method may only be called from the goroutine that 'owns' the Runtime, it may not be called concurrently.

func (ArrayBuffer) Detached

func (a ArrayBuffer) Detached() bool

Detached returns true if the ArrayBuffer is detached.

type Callable

type Callable func(this Value, args ...Value) (Value, error)

Callable represents a JavaScript function that can be called from Go.

func AssertFunction

func AssertFunction(v Value) (Callable, bool)

AssertFunction checks if the Value is a function and returns a Callable.

Example
vm := New()
_, err := vm.RunString(`
	function sum(a, b) {
		return a+b;
	}
	`)
if err != nil {
	panic(err)
}
sum, ok := AssertFunction(vm.Get("sum"))
if !ok {
	panic("Not a function")
}

res, err := sum(Undefined(), vm.ToValue(40), vm.ToValue(2))
if err != nil {
	panic(err)
}
fmt.Println(res)
Output:

42

type CompilerError

type CompilerError struct {
	Message string
	File    *SrcFile
	Offset  int
}

type CompilerReferenceError

type CompilerReferenceError struct {
	CompilerError
}

func (*CompilerReferenceError) Error

func (e *CompilerReferenceError) Error() string

type CompilerSyntaxError

type CompilerSyntaxError struct {
	CompilerError
}

func (*CompilerSyntaxError) Error

func (e *CompilerSyntaxError) Error() string

type ConstructorCall

type ConstructorCall struct {
	This      *Object
	Arguments []Value
}

func (ConstructorCall) Argument

func (f ConstructorCall) Argument(idx int) Value

type Exception

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

func (*Exception) Error

func (e *Exception) Error() string

func (*Exception) String

func (e *Exception) String() string

func (*Exception) Value

func (e *Exception) Value() Value

type FieldNameMapper

type FieldNameMapper interface {
	// FieldName returns a JavaScript name for the given struct field in the given type.
	// If this method returns "" the field becomes hidden.
	FieldName(t reflect.Type, f reflect.StructField) string

	// MethodName returns a JavaScript name for the given method in the given type.
	// If this method returns "" the method becomes hidden.
	MethodName(t reflect.Type, m reflect.Method) string
}

FieldNameMapper provides custom mapping between Go and JavaScript property names.

A FieldNameMapper may optionally have a SkipValue method for advanced mapping that depend on the actual value:

// SkipValue returns a function that allows custom values (typically zero values) to be skipped SkipValue(t reflect.Type, f reflect.StructField) func(reflect.Value) bool

func TagFieldNameMapper

func TagFieldNameMapper(tagName string, uncapMethods bool) FieldNameMapper

TagFieldNameMapper returns a FieldNameMapper that uses the given tagName for struct fields and optionally uncapitalises (making the first letter lower case) method names. The common tag value syntax is supported (name[,options]), however options are ignored. Setting name to anything other than a valid ECMAScript identifier makes the field hidden.

Example
vm := New()
vm.SetFieldNameMapper(TagFieldNameMapper("json", true))
type S struct {
	Field int `json:"field"`
}
vm.Set("s", S{Field: 42})
res, _ := vm.RunString(`s.field`)
fmt.Println(res.Export())
Output:

42

func UncapFieldNameMapper

func UncapFieldNameMapper() FieldNameMapper

UncapFieldNameMapper returns a FieldNameMapper that uncapitalises struct field and method names making the first letter lower case.

Example
vm := New()
s := testGoReflectMethod_O{
	Test: "passed",
}
vm.SetFieldNameMapper(UncapFieldNameMapper())
vm.Set("s", s)
res, _ := vm.RunString(`s.test + " and " + s.method("passed too")`)
fmt.Println(res.Export())
Output:

passed and passed too

type Flag

type Flag int
const (
	FLAG_NOT_SET Flag = iota
	FLAG_FALSE
	FLAG_TRUE
)

func ToFlag

func ToFlag(b bool) Flag

func (Flag) Bool

func (f Flag) Bool() bool

type FunctionCall

type FunctionCall struct {
	This      Value
	Arguments []Value
}

func (FunctionCall) Argument

func (f FunctionCall) Argument(idx int) Value

type InterruptedError

type InterruptedError struct {
	Exception
	// contains filtered or unexported fields
}

func (*InterruptedError) Error

func (e *InterruptedError) Error() string

func (*InterruptedError) String

func (e *InterruptedError) String() string

func (*InterruptedError) Value

func (e *InterruptedError) Value() interface{}

type JsonEncodable

type JsonEncodable interface {
	JsonEncodable() interface{}
}

JsonEncodable allows custom JSON encoding by JSON.stringify() Note that if the returned value itself also implements JsonEncodable, it won't have any effect.

type Now

type Now func() time.Time

type Object

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

func (*Object) ClassName

func (o *Object) ClassName() string

ClassName returns the class name

func (*Object) DefineAccessorProperty

func (o *Object) DefineAccessorProperty(name string, getter, setter Value, configurable, enumerable Flag) error

DefineAccessorProperty is a Go equivalent of Object.defineProperty(o, name, {get: getter, set: setter, configurable: configurable, enumerable: enumerable})

func (*Object) DefineDataProperty

func (o *Object) DefineDataProperty(name string, value Value, writable, configurable, enumerable Flag) error

DefineDataProperty is a Go equivalent of Object.defineProperty(o, name, {value: value, writable: writable, configurable: configurable, enumerable: enumerable})

func (*Object) Equals

func (o *Object) Equals(other Value) bool

func (*Object) Export

func (o *Object) Export() interface{}

func (*Object) ExportType

func (o *Object) ExportType() reflect.Type

func (*Object) Get

func (o *Object) Get(name string) Value

func (*Object) Keys

func (o *Object) Keys() (keys []string)

func (*Object) MarshalJSON

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

MarshalJSON returns JSON representation of the Object. It is equivalent to JSON.stringify(o). Note, this implements json.Marshaler so that json.Marshal() can be used without the need to Export().

func (*Object) SameAs

func (o *Object) SameAs(other Value) bool

func (*Object) Set

func (o *Object) Set(name string, value interface{}) error

func (*Object) StrictEquals

func (o *Object) StrictEquals(other Value) bool

func (*Object) String

func (o *Object) String() string

func (*Object) ToBoolean

func (o *Object) ToBoolean() bool

func (*Object) ToFloat

func (o *Object) ToFloat() float64

func (*Object) ToInteger

func (o *Object) ToInteger() int64

func (*Object) ToNumber

func (o *Object) ToNumber() Value

func (*Object) ToObject

func (o *Object) ToObject(*Runtime) *Object

func (*Object) ToString

func (o *Object) ToString() Value

type Position

type Position struct {
	Line, Col int
}

func (Position) String

func (p Position) String() string

type Program

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

func Compile

func Compile(name, src string, strict bool) (*Program, error)

Compile creates an internal representation of the JavaScript code that can be later run using the Runtime.RunProgram() method. This representation is not linked to a runtime in any way and can be run in multiple runtimes (possibly at the same time).

func CompileAST

func CompileAST(prg *js_ast.Program, strict bool) (*Program, error)

CompileAST creates an internal representation of the JavaScript code that can be later run using the Runtime.RunProgram() method. This representation is not linked to a runtime in any way and can be run in multiple runtimes (possibly at the same time).

func MustCompile

func MustCompile(name, src string, strict bool) *Program

MustCompile is like Compile but panics if the code cannot be compiled. It simplifies safe initialization of global variables holding compiled JavaScript code.

type PropertyDescriptor

type PropertyDescriptor struct {
	Value Value

	Writable, Configurable, Enumerable Flag

	Getter, Setter Value
	// contains filtered or unexported fields
}

func (*PropertyDescriptor) Empty

func (p *PropertyDescriptor) Empty() bool

type Proxy

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

Proxy is a Go wrapper around ECMAScript Proxy. Calling Runtime.ToValue() on it returns the underlying Proxy. Calling Export() on an ECMAScript Proxy returns a wrapper. Use Runtime.NewProxy() to create one.

func (Proxy) Revoke

func (p Proxy) Revoke()

type ProxyTrapConfig

type ProxyTrapConfig struct {
	// A trap for Object.getPrototypeOf, Reflect.getPrototypeOf, __proto__, Object.prototype.isPrototypeOf, instanceof
	GetPrototypeOf func(target *Object) (prototype *Object)

	// A trap for Object.setPrototypeOf, Reflect.setPrototypeOf
	SetPrototypeOf func(target *Object, prototype *Object) (success bool)

	// A trap for Object.isExtensible, Reflect.isExtensible
	IsExtensible func(target *Object) (success bool)

	// A trap for Object.preventExtensions, Reflect.preventExtensions
	PreventExtensions func(target *Object) (success bool)

	// A trap for Object.getOwnPropertyDescriptor, Reflect.getOwnPropertyDescriptor
	GetOwnPropertyDescriptor func(target *Object, prop string) (propertyDescriptor PropertyDescriptor)

	// A trap for Object.defineProperty, Reflect.defineProperty
	DefineProperty func(target *Object, key string, propertyDescriptor PropertyDescriptor) (success bool)

	// A trap for the in operator, with operator, Reflect.has
	Has func(target *Object, property string) (available bool)

	// A trap for getting property values, Reflect.get
	Get func(target *Object, property string, receiver *Object) (value Value)

	// A trap for setting property values, Reflect.set
	Set func(target *Object, property string, value Value, receiver *Object) (success bool)

	// A trap for the delete operator, Reflect.deleteProperty
	DeleteProperty func(target *Object, property string) (success bool)

	// A trap for Object.getOwnPropertyNames, Object.getOwnPropertySymbols, Object.keys, Reflect.ownKeys
	OwnKeys func(target *Object) (object *Object)

	// A trap for a function call, Function.prototype.apply, Function.prototype.call, Reflect.apply
	Apply func(target *Object, this *Object, argumentsList []Value) (value Value)

	// A trap for the new operator, Reflect.construct
	Construct func(target *Object, argumentsList []Value, newTarget *Object) (value *Object)
}

ProxyTrapConfig provides a simplified Go-friendly API for implementing Proxy traps. Note that the Proxy may not have Symbol properties when using this as a handler because property keys are passed as strings. get() and getOwnPropertyDescriptor() for Symbol properties will always return undefined; has() and deleteProperty() for Symbol properties will always return false; set() and defineProperty() for Symbol properties will throw a TypeError. If you need Symbol properties implement the handler in JavaScript.

type RandSource

type RandSource func() float64

type Runtime

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

func New

func New() *Runtime

New creates an instance of a Javascript runtime that can be used to run code. Multiple instances may be created and used simultaneously, however it is not possible to pass JS values across runtimes.

func (*Runtime) CaptureCallStack

func (r *Runtime) CaptureCallStack(depth int, stack []StackFrame) []StackFrame

CaptureCallStack appends the current call stack frames to the stack slice (which may be nil) up to the specified depth. The most recent frame will be the first one. If depth <= 0 or more than the number of available frames, returns the entire stack.

func (*Runtime) ClearInterrupt

func (r *Runtime) ClearInterrupt()

ClearInterrupt resets the interrupt flag. Typically this needs to be called before the runtime is made available for re-use if there is a chance it could have been interrupted with Interrupt(). Otherwise if Interrupt() was called when runtime was not running (e.g. if it had already finished) so that Interrupt() didn't actually trigger, an attempt to use the runtime will immediately cause an interruption. It is up to the user to ensure proper synchronisation so that ClearInterrupt() is only called when the runtime has finished and there is no chance of a concurrent Interrupt() call.

func (*Runtime) CreateObject

func (r *Runtime) CreateObject(proto *Object) *Object

CreateObject creates an object with given prototype. Equivalent of Object.create(proto).

func (*Runtime) ExportTo

func (r *Runtime) ExportTo(v Value, target interface{}) error

ExportTo converts a JavaScript value into the specified Go value. The second parameter must be a non-nil pointer. Exporting to an interface{} results in a value of the same type as Export() would produce. Exporting to numeric types uses the standard ECMAScript conversion operations, same as used when assigning values to non-clamped typed array items, e.g. https://www.ecma-international.org/ecma-262/10.0/index.html#sec-toint32 Returns error if conversion is not possible.

Example (Func)
const SCRIPT = `
	function f(param) {
		return +param + 2;
	}
	`

vm := New()
_, err := vm.RunString(SCRIPT)
if err != nil {
	panic(err)
}

var fn func(string) string
err = vm.ExportTo(vm.Get("f"), &fn)
if err != nil {
	panic(err)
}

fmt.Println(fn("40")) // note, _this_ value in the function will be undefined.
Output:

42
Example (FuncThrow)
const SCRIPT = `
	function f(param) {
		throw new Error("testing");
	}
	`

vm := New()
_, err := vm.RunString(SCRIPT)
if err != nil {
	panic(err)
}

var fn func(string) (string, error)
err = vm.ExportTo(vm.Get("f"), &fn)
if err != nil {
	panic(err)
}
_, err = fn("")

fmt.Println(err)
Output:

Error: testing at f (<eval>:3:9(4))
Example (FuncVariadic)
const SCRIPT = `
	function f() {
		return Array.prototype.join.call(arguments, ",");
	}
	`
vm := New()
_, err := vm.RunString(SCRIPT)
if err != nil {
	panic(err)
}

var fn func(args ...interface{}) string
err = vm.ExportTo(vm.Get("f"), &fn)
if err != nil {
	panic(err)
}
fmt.Println(fn("a", "b", 42))
Output:

a,b,42

func (*Runtime) Get

func (r *Runtime) Get(name string) Value

Get the specified property of the global object.

func (*Runtime) GlobalObject

func (r *Runtime) GlobalObject() *Object

GlobalObject returns the global object.

func (*Runtime) Interrupt

func (r *Runtime) Interrupt(v interface{})

Interrupt a running JavaScript. The corresponding Go call will return an *InterruptedError containing v. Note, it only works while in JavaScript code, it does not interrupt native Go functions (which includes all built-ins). If the runtime is currently not running, it will be immediately interrupted on the next Run*() call. To avoid that use ClearInterrupt()

func (*Runtime) New

func (r *Runtime) New(construct Value, args ...Value) (o *Object, err error)

New is an equivalent of the 'new' operator allowing to call it directly from Go.

func (*Runtime) NewArrayBuffer

func (r *Runtime) NewArrayBuffer(data []byte) ArrayBuffer

func (*Runtime) NewGoError

func (r *Runtime) NewGoError(err error) *Object

func (*Runtime) NewObject

func (r *Runtime) NewObject() (v *Object)

func (*Runtime) NewProxy

func (r *Runtime) NewProxy(target *Object, nativeHandler *ProxyTrapConfig) Proxy

func (*Runtime) NewTypeError

func (r *Runtime) NewTypeError(args ...interface{}) *Object

func (*Runtime) RunProgram

func (r *Runtime) RunProgram(p *Program) (result Value, err error)

RunProgram executes a pre-compiled (see Compile()) code in the global context.

func (*Runtime) RunScript

func (r *Runtime) RunScript(name, src string) (Value, error)

RunScript executes the given string in the global context.

func (*Runtime) RunString

func (r *Runtime) RunString(str string) (Value, error)

RunString executes the given string in the global context.

func (*Runtime) Set

func (r *Runtime) Set(name string, value interface{})

Set the specified value as a property of the global object. The value is first converted using ToValue()

func (*Runtime) SetFieldNameMapper

func (r *Runtime) SetFieldNameMapper(mapper FieldNameMapper)

SetFieldNameMapper sets a custom field name mapper for Go types. It can be called at any time, however the mapping for any given value is fixed at the point of creation. Setting this to nil restores the default behaviour which is all exported fields and methods are mapped to their original unchanged names.

func (*Runtime) SetRandSource

func (r *Runtime) SetRandSource(source RandSource)

SetRandSource sets random source for this Runtime. If not called, the default math/rand is used.

func (*Runtime) SetTimeSource

func (r *Runtime) SetTimeSource(now Now)

SetTimeSource sets the current time source for this Runtime. If not called, the default time.Now() is used.

func (*Runtime) ToValue

func (r *Runtime) ToValue(i interface{}) Value

ToValue converts a Go value into a JavaScript value of a most appropriate type. Structural types (such as structs, maps and slices) are wrapped so that changes are reflected on the original value which can be retrieved using Value.Export().

Notes on individual types:

Primitive types

Primitive types (numbers, string, bool) are converted to the corresponding JavaScript primitives.

Strings

Because of the difference in internal string representation between ECMAScript (which uses UTF-16) and Go (which uses UTF-8) conversion from JS to Go may be lossy. In particular, code points that can be part of UTF-16 surrogate pairs (0xD800-0xDFFF) cannot be represented in UTF-8 unless they form a valid surrogate pair and are replaced with utf8.RuneError.

Nil

Nil is converted to null.

Functions

func(FunctionCall) Value is treated as a native JavaScript function. This increases performance because there are no automatic argument and return value type conversions (which involves reflect).

Any other Go function is wrapped so that the arguments are automatically converted into the required Go types and the return value is converted to a JavaScript value (using this method). If conversion is not possible, a TypeError is thrown.

Functions with multiple return values return an Array. If the last return value is an `error` it is not returned but converted into a JS exception. If the error is *Exception, it is thrown as is, otherwise it's wrapped in a GoEerror. Note that if there are exactly two return values and the last is an `error`, the function returns the first value as is, not an Array.

Structs

Structs are converted to Object-like values. Fields and methods are available as properties, their values are results of this method (ToValue()) applied to the corresponding Go value.

Field properties are writable (if the struct is addressable) and non-configurable. Method properties are non-writable and non-configurable.

Attempt to define a new property or delete an existing property will fail (throw in strict mode) unless it's a Symbol property. Symbol properties only exist in the wrapper and do not affect the underlying Go value. Note that because a wrapper is created every time a property is accessed it may lead to unexpected results such as this:

 type Field struct{
 }
 type S struct {
	Field *Field
 }
 var s = S{
	Field: &Field{},
 }
 vm := New()
 vm.Set("s", &s)
 res, err := vm.RunString(`
 var sym = Symbol(66);
 var field1 = s.Field;
 field1[sym] = true;
 var field2 = s.Field;
 field1 === field2; // true, because the equality operation compares the wrapped values, not the wrappers
 field1[sym] === true; // true
 field2[sym] === undefined; // also true
 `)

The same applies to values from maps and slices as well.

Handling of time.Time

time.Time does not get special treatment and therefore is converted just like any other `struct` providing access to all its methods. This is done deliberately instead of converting it to a `Date` because these two types are not fully compatible: `time.Time` includes zone, whereas JS `Date` doesn't. Doing the conversion implicitly therefore would result in a loss of information.

If you need to convert it to a `Date`, it can be done either in JS:

var d = new Date(goval.UnixNano()/1e6);

... or in Go:

 now := time.Now()
 vm := New()
 val, err := vm.New(vm.Get("Date").ToObject(vm), vm.ToValue(now.UnixNano()/1e6))
 if err != nil {
	...
 }
 vm.Set("d", val)

Note that Value.Export() for a `Date` value returns time.Time in local timezone.

Maps

Maps with string or integer key type are converted into host objects that largely behave like a JavaScript Object.

Maps with methods

If a map type has at least one method defined, the properties of the resulting Object represent methods, not map keys. This is because in JavaScript there is no distinction between 'object.key` and `object[key]`, unlike Go. If access to the map values is required, it can be achieved by defining another method or, if it's not possible, by defining an external getter function.

Slices

Slices are converted into host objects that behave largely like JavaScript Array. It has the appropriate prototype and all the usual methods should work. There are, however, some caveats:

- If the slice is not addressable, the array cannot be extended or shrunk. Any attempt to do so (by setting an index beyond the current length or by modifying the length) will result in a TypeError.

- Converted Arrays may not contain holes (because Go slices cannot). This means that hasOwnProperty(n) will always return `true` if n < length. Attempt to delete an item with an index < length will fail. Nil slice elements will be converted to `null`. Accessing an element beyond `length` will return `undefined`.

Any other type is converted to a generic reflect based host object. Depending on the underlying type it behaves similar to a Number, String, Boolean or Object.

Note that the underlying type is not lost, calling Export() returns the original Go value. This applies to all reflect based types.

type SrcFile

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

func NewSrcFile

func NewSrcFile(name, src string, sourceMap *sourcemap.Consumer) *SrcFile

func (*SrcFile) Position

func (f *SrcFile) Position(offset int) Position

type StackFrame

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

func (*StackFrame) FuncName

func (f *StackFrame) FuncName() string

func (*StackFrame) Position

func (f *StackFrame) Position() Position

func (*StackFrame) SrcName

func (f *StackFrame) SrcName() string

func (*StackFrame) Write

func (f *StackFrame) Write(b *bytes.Buffer)

type Value

type Value interface {
	ToInteger() int64

	ToString() Value
	String() string
	ToFloat() float64
	ToNumber() Value
	ToBoolean() bool
	ToObject(*Runtime) *Object
	SameAs(Value) bool
	Equals(Value) bool
	StrictEquals(Value) bool
	Export() interface{}
	ExportType() reflect.Type
	// contains filtered or unexported methods
}

func NaN

func NaN() Value

NaN returns a JS NaN value.

func NegativeInf

func NegativeInf() Value

NegativeInf returns a JS -Inf value.

func Null

func Null() Value

Null returns JS null value.

func PositiveInf

func PositiveInf() Value

PositiveInf returns a JS +Inf value.

func Undefined

func Undefined() Value

Undefined returns JS undefined value. Note if global 'undefined' property is changed this still returns the original value.

Directories

Path Synopsis
Package ast declares types representing a JavaScript AST.
Package ast declares types representing a JavaScript AST.
Package file encapsulates the file abstractions used by the ast & parser.
Package file encapsulates the file abstractions used by the ast & parser.
Package ftoa provides ECMAScript-compliant floating point number conversion to string.
Package ftoa provides ECMAScript-compliant floating point number conversion to string.
internal/fast
Package fast contains code ported from V8 (https://github.com/v8/v8/blob/master/src/numbers/fast-dtoa.cc) See LICENSE_V8 for the original copyright message and disclaimer.
Package fast contains code ported from V8 (https://github.com/v8/v8/blob/master/src/numbers/fast-dtoa.cc) See LICENSE_V8 for the original copyright message and disclaimer.
Package parser implements a parser for JavaScript.
Package parser implements a parser for JavaScript.
Package token defines constants representing the lexical tokens of JavaScript (ECMA5).
Package token defines constants representing the lexical tokens of JavaScript (ECMA5).
Package unistring contains an implementation of a hybrid ASCII/UTF-16 string.
Package unistring contains an implementation of a hybrid ASCII/UTF-16 string.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL