base on ECMAScript/JavaScript engine in pure Go goja ==== ECMAScript 5.1(+) implementation in Go. [](https://pkg.go.dev/github.com/dop251/goja) 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](https://github.com/robertkrimen/otto). The minimum required Go version is 1.20. Features -------- * Full ECMAScript 5.1 support (including regex and strict mode). * Passes nearly all [tc39 tests](https://github.com/tc39/test262) for the features implemented so far. The goal is to pass all of them. See .tc39_test262_checkout.sh for the latest working commit id. * Capable of running Babel, Typescript compiler and pretty much anything written in ES5. * Sourcemaps. * Most of ES6 functionality, still work in progress, see https://github.com/dop251/goja/milestone/1?closed=1 Known incompatibilities and caveats ----------------------------------- ### WeakMap WeakMap is implemented by embedding references to the values into the keys. This means that as long as the key is reachable all values associated with it in any weak maps also remain reachable and therefore cannot be garbage collected even if they are not otherwise referenced, even after the WeakMap is gone. The reference to the value is dropped either when the key is explicitly removed from the WeakMap or when the key becomes unreachable. To illustrate this: ```javascript var m = new WeakMap(); var key = {}; var value = {/* a very large object */}; m.set(key, value); value = undefined; m = undefined; // The value does NOT become garbage-collectable at this point key = undefined; // Now it does // m.delete(key); // This would work too ``` The reason for it is the limitation of the Go runtime. At the time of writing (version 1.15) having a finalizer set on an object which is part of a reference cycle makes the whole cycle non-garbage-collectable. The solution above is the only reasonable way I can think of without involving finalizers. This is the third attempt (see https://github.com/dop251/goja/issues/250 and https://github.com/dop251/goja/issues/199 for more details). Note, this does not have any effect on the application logic, but may cause a higher-than-expected memory usage. ### WeakRef and FinalizationRegistry For the reason mentioned above implementing WeakRef and FinalizationRegistry does not seem to be possible at this stage. ### JSON `JSON.parse()` uses the standard Go library which operates in UTF-8. Therefore, it cannot correctly parse broken UTF-16 surrogate pairs, for example: ```javascript JSON.parse(`"\\uD800"`).charCodeAt(0).toString(16) // returns "fffd" instead of "d800" ``` ### Date Conversion from calendar date to epoch timestamp uses the standard Go library which uses `int`, rather than `float` as per ECMAScript specification. This means if you pass arguments that overflow int to the `Date()` constructor or if there is an integer overflow, the result will be incorrect, for example: ```javascript Date.UTC(1970, 0, 1, 80063993375, 29, 1, -288230376151711740) // returns 29256 instead of 29312 ``` 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](https://github.com/dop251/goja/issues/2). ### 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](https://github.com/dop251/goja_nodejs) aimed at providing some NodeJS functionality, and it includes an event loop. ### Can you implement (feature X from ES6 or higher)? I will be adding features in their dependency order and as quickly as time permits. Please do not ask for ETAs. Features that are open in the [milestone](https://github.com/dop251/goja/milestone/1) are either in progress or will be worked on next. The ongoing work is done in separate feature branches which are merged into master when appropriate. Every commit in these branches 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 there are (usually) no major breaking changes between ECMAScript revisions it should not break your existing code. You are encouraged to give it a try and report any bugs found. Please do not submit fixes though without discussing it first, as the code could be changed in the meantime. ### 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 ------------- Run JavaScript and get the result value. ```go 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](https://pkg.go.dev/github.com/dop251/goja#Runtime.ToValue) 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()](https://pkg.go.dev/github.com/dop251/goja#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: - Using [AssertFunction()](https://pkg.go.dev/github.com/dop251/goja#AssertFunction): ```go const SCRIPT = ` function sum(a, b) { return +a + b; } ` vm := goja.New() _, err := vm.RunString(SCRIPT) if err != nil { panic(err) } sum, ok := goja.AssertFunction(vm.Get("sum")) if !ok { panic("Not a function") } res, err := sum(goja.Undefined(), vm.ToValue(40), vm.ToValue(2)) if err != nil { panic(err) } fmt.Println(res) // Output: 42 ``` - Using [Runtime.ExportTo()](https://pkg.go.dev/github.com/dop251/goja#Runtime.ExportTo): ```go const SCRIPT = ` function sum(a, b) { return +a + b; } ` vm := goja.New() _, err := vm.RunString(SCRIPT) if err != nil { panic(err) } var sum func(int, int) int err = vm.ExportTo(vm.Get("sum"), &sum) if err != nil { panic(err) } fmt.Println(sum(40, 2)) // 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](https://pkg.go.dev/github.com/dop251/goja#FieldNameMapper): ```go vm := goja.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](https://pkg.go.dev/github.com/dop251/goja#TagFieldNameMapper) and [UncapFieldNameMapper](https://pkg.go.dev/github.com/dop251/goja#UncapFieldNameMapper), or you can use your own implementation. Native Constructors ------------------- In order to implement a constructor function in Go use `func (goja.ConstructorCall) *goja.Object`. See [Runtime.ToValue()](https://pkg.go.dev/github.com/dop251/goja#Runtime.ToValue) documentation for more details. Regular Expressions ------------------- Goja uses the embedded Go regexp library where possible, otherwise it falls back to [regexp2](https://github.com/dlclark/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: ```go vm := goja.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): ```go var vm *Runtime func Test() { panic(vm.ToValue("Error")) } vm = goja.New() vm.Set("Test", Test) _, err := vm.RunString(` try { Test(); } catch(e) { if (e !== "Error") { throw e; } } `) if err != nil { panic(err) } ``` Interrupting ------------ ```go func TestInterrupt(t *testing.T) { const SCRIPT = ` var i = 0; for (;;) { i++; } ` vm := goja.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](https://github.com/dop251/goja_nodejs) aimed at providing some of the NodeJS functionality. ", Assign "at most 3 tags" to the expected json: {"id":"11703","tags":[]} "only from the tags list I provide: [{"id":77,"name":"3d"},{"id":89,"name":"agent"},{"id":17,"name":"ai"},{"id":54,"name":"algorithm"},{"id":24,"name":"api"},{"id":44,"name":"authentication"},{"id":3,"name":"aws"},{"id":27,"name":"backend"},{"id":60,"name":"benchmark"},{"id":72,"name":"best-practices"},{"id":39,"name":"bitcoin"},{"id":37,"name":"blockchain"},{"id":1,"name":"blog"},{"id":45,"name":"bundler"},{"id":58,"name":"cache"},{"id":21,"name":"chat"},{"id":49,"name":"cicd"},{"id":4,"name":"cli"},{"id":64,"name":"cloud-native"},{"id":48,"name":"cms"},{"id":61,"name":"compiler"},{"id":68,"name":"containerization"},{"id":92,"name":"crm"},{"id":34,"name":"data"},{"id":47,"name":"database"},{"id":8,"name":"declarative-gui "},{"id":9,"name":"deploy-tool"},{"id":53,"name":"desktop-app"},{"id":6,"name":"dev-exp-lib"},{"id":59,"name":"dev-tool"},{"id":13,"name":"ecommerce"},{"id":26,"name":"editor"},{"id":66,"name":"emulator"},{"id":62,"name":"filesystem"},{"id":80,"name":"finance"},{"id":15,"name":"firmware"},{"id":73,"name":"for-fun"},{"id":2,"name":"framework"},{"id":11,"name":"frontend"},{"id":22,"name":"game"},{"id":81,"name":"game-engine "},{"id":23,"name":"graphql"},{"id":84,"name":"gui"},{"id":91,"name":"http"},{"id":5,"name":"http-client"},{"id":51,"name":"iac"},{"id":30,"name":"ide"},{"id":78,"name":"iot"},{"id":40,"name":"json"},{"id":83,"name":"julian"},{"id":38,"name":"k8s"},{"id":31,"name":"language"},{"id":10,"name":"learning-resource"},{"id":33,"name":"lib"},{"id":41,"name":"linter"},{"id":28,"name":"lms"},{"id":16,"name":"logging"},{"id":76,"name":"low-code"},{"id":90,"name":"message-queue"},{"id":42,"name":"mobile-app"},{"id":18,"name":"monitoring"},{"id":36,"name":"networking"},{"id":7,"name":"node-version"},{"id":55,"name":"nosql"},{"id":57,"name":"observability"},{"id":46,"name":"orm"},{"id":52,"name":"os"},{"id":14,"name":"parser"},{"id":74,"name":"react"},{"id":82,"name":"real-time"},{"id":56,"name":"robot"},{"id":65,"name":"runtime"},{"id":32,"name":"sdk"},{"id":71,"name":"search"},{"id":63,"name":"secrets"},{"id":25,"name":"security"},{"id":85,"name":"server"},{"id":86,"name":"serverless"},{"id":70,"name":"storage"},{"id":75,"name":"system-design"},{"id":79,"name":"terminal"},{"id":29,"name":"testing"},{"id":12,"name":"ui"},{"id":50,"name":"ux"},{"id":88,"name":"video"},{"id":20,"name":"web-app"},{"id":35,"name":"web-server"},{"id":43,"name":"webassembly"},{"id":69,"name":"workflow"},{"id":87,"name":"yaml"}]" returns me the "expected json"