proposal: syscall/js: method or function to await a js.Value

[jcbhmr]

Proposal Details

Let's say I have an async JavaScript function:

globalThis.myAsyncFunction = async () => 42;

Ideally I would be able to do one of these:

var n int
n = js.Global().Call("myAsyncFunction").Wait().Int()
n = js.Global().Call("myAsyncFunction").Await().Int()
n = js.Await(js.Global().Call("myAsyncFunction")).Int()
n = (<-js.Global().Call("myAsyncFunction").Chan()).Int()

Creating a promise in Go code for use by JavaScript code is ok-ish (it's not great): just use the new Promise(callback) constructor with a Go-defined js.Func callback.

var jsDoThingCallback = js.FuncOf(func(this Value, args []Value) interface{} {
	r1 := <-myChannelFromSomewhere
	r2, err := someFuncThatUsesChans(r1)
	if err != nil {
		args[1].Invoke(errorConstructor.New(err.Error()))
		return nil
	}
	r3, err := someFuncThatSleeps(r2)
	if err != nil {
		args[1].Invoke(errorConstructor.New(err.Error()))
		return nil
	}
	args[0].Invoke(r3)
	return nil
})
func DoThingAsync() js.Value {
	return promiseConstructor.New(jsDoThingCallback)
}

The other direction -- unwrapping a JavaScript Promise instance on the Go-side by waiting for it -- is worse.

// Ugh. I have to manage this intermediate channel myself and remember to handle some edge cases.
var n int
p := promiseConstructor.Call("resolve", js.Global().Call("myAsyncFunction"))
type result struct {
	value js.Value
	err error
}
ch := make(chan result, 1)
onFulfilled := js.FuncOf(func(this js.Value, args []js.Value) interface{} {
	ch <- result{args[0], nil}
	close(ch)
	return nil
})
defer onFulfilled.Release()
onRejected := js.FuncOf(func(this js.Value, args []js.Value) interface{} {
	ch <- result{js.Value{}, js.Error{args[0]}}
	close(ch)
	return nil
})
defer onRejected.Release()
p.Call("then", onFulfilled, onRejected)
r := <-ch
if r.err != nil {
	panic(r.err)
}
n = r.value.Int()
// Would have to do *all that again* for another `await nextFunctionThatUsesResult(n)` 😭

Here's the algorithm for the ECMAScript 2025 Await( value ) abstract operation: https://tc39.es/ecma262/multipage/control-abstraction-objects.html#await

It seems like the .Wait() method convention is already in the standard library with sync.WaitGroup wg.Wait(). Here's an idea for how that might look in Go code. I'm not a Go channels wizard so this might be the completely wrong way to do this.

// Wait waits for the thenable v to fulfill or reject and returns the resulting value or error.
// This is equivalent to the await operator in JavaScript.
func (v js.Value) Wait() (js.Value, error) {
	p := promiseConstructor.Call("resolve", v)
	type result struct {
		value js.Value
		err error
	}
	ch := make(chan result, 1)
	onFulfilled := js.FuncOf(func(this js.Value, args []js.Value) interface{} {
		ch <- result{args[0], nil}
		close(ch)
		return nil
	})
	defer onFulfilled.Release()
	onRejected := js.FuncOf(func(this js.Value, args []js.Value) interface{} {
		ch <- result{js.Value{}, js.Error{args[0]}}
		close(ch)
		return nil
	})
	defer onRejected.Release()
	p.Call("then", onFulfilled, onRejected)
	r := <-ch
	// Unsure if want to panic on error, or return the error.
	// If a synchronous function throws an error it panics. Don't know whether to stick
	// to that convention or to return a (js.Value, error) multivalue.
	return r.value, r.err
	// OR
	if r.err == nil {
		return r.value
	} else {
		panic(r.err)
	}
}

There's already some of this promise stuff in the Go standard library

go/src/net/http/roundtrip_js.go

Lines 129 to 245 in 1d0f5c4

	fetchPromise := js.Global().Call("fetch", req.URL.String(), opt)
	var (
	respCh = make(chan *Response, 1)
	errCh = make(chan error, 1)
	success, failure js.Func
	)
	success = js.FuncOf(func(this js.Value, args []js.Value) any {
	success.Release()
	failure.Release()
	result := args[0]
	header := Header{}
	// https://developer.mozilla.org/en-US/docs/Web/API/Headers/entries
	headersIt := result.Get("headers").Call("entries")
	for {
	n := headersIt.Call("next")
	if n.Get("done").Bool() {
	break
	}
	pair := n.Get("value")
	key, value := pair.Index(0).String(), pair.Index(1).String()
	ck := CanonicalHeaderKey(key)
	header[ck] = append(header[ck], value)
	}
	contentLength := int64(0)
	clHeader := header.Get("Content-Length")
	switch {
	case clHeader != "":
	cl, err := strconv.ParseInt(clHeader, 10, 64)
	if err != nil {
	errCh <- fmt.Errorf("net/http: ill-formed Content-Length header: %v", err)
	return nil
	}
	if cl < 0 {
	// Content-Length values less than 0 are invalid.
	// See: https://datatracker.ietf.org/doc/html/rfc2616/#section-14.13
	errCh <- fmt.Errorf("net/http: invalid Content-Length header: %q", clHeader)
	return nil
	}
	contentLength = cl
	default:
	// If the response length is not declared, set it to -1.
	contentLength = -1
	}
	b := result.Get("body")
	var body io.ReadCloser
	// The body is undefined when the browser does not support streaming response bodies (Firefox),
	// and null in certain error cases, i.e. when the request is blocked because of CORS settings.
	if !b.IsUndefined() && !b.IsNull() {
	body = &streamReader{stream: b.Call("getReader")}
	} else {
	// Fall back to using ArrayBuffer
	// https://developer.mozilla.org/en-US/docs/Web/API/Body/arrayBuffer
	body = &arrayReader{arrayPromise: result.Call("arrayBuffer")}
	}
	code := result.Get("status").Int()
	uncompressed := false
	if ascii.EqualFold(header.Get("Content-Encoding"), "gzip") {
	// The fetch api will decode the gzip, but Content-Encoding not be deleted.
	header.Del("Content-Encoding")
	header.Del("Content-Length")
	contentLength = -1
	uncompressed = true
	}
	respCh <- &Response{
	Status: fmt.Sprintf("%d %s", code, StatusText(code)),
	StatusCode: code,
	Header: header,
	ContentLength: contentLength,
	Uncompressed: uncompressed,
	Body: body,
	Request: req,
	}
	return nil
	})
	failure = js.FuncOf(func(this js.Value, args []js.Value) any {
	success.Release()
	failure.Release()
	err := args[0]
	// The error is a JS Error type
	// https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error
	// We can use the toString() method to get a string representation of the error.
	errMsg := err.Call("toString").String()
	// Errors can optionally contain a cause.
	if cause := err.Get("cause"); !cause.IsUndefined() {
	// The exact type of the cause is not defined,
	// but if it's another error, we can call toString() on it too.
	if !cause.Get("toString").IsUndefined() {
	errMsg += ": " + cause.Call("toString").String()
	} else if cause.Type() == js.TypeString {
	errMsg += ": " + cause.String()
	}
	}
	errCh <- fmt.Errorf("net/http: fetch() failed: %s", errMsg)
	return nil
	})
	fetchPromise.Call("then", success, failure)
	select {
	case <-req.Context().Done():
	if !ac.IsUndefined() {
	// Abort the Fetch request.
	ac.Call("abort")
	}
	return nil, req.Context().Err()
	case resp := <-respCh:
	return resp, nil
	case err := <-errCh:
	return nil, err
	}

so it seems like this is a thing that people need to do. I think that providing a .Wait() or Await(v) or something would be a good way to "one good way to do it"-ify this.

[gabyhelp]

Related Issues and Documentation

• misc/wasm: Support Go function call javascript Promise function #28911 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[jcbhmr]

That issue #28911 that @gabyhelp linked is kinda what I want but it went unresolved. https://go-review.googlesource.com/c/go/+/150917 which was spawned from the issue linked was abandoned. The reasoning given seemed to be of the "this doesn't belong in the standard library" vibe.

I am a bit wary of adding new API like this. We can already achieve this by manually calling the "then" function ourselves, which the net/http library already does.

This is just syntactic sugar and I am afraid might add precedent for adding more helpers like this.

I'm in the same boat: I think this is API creep. And I (now) feel the same about https://go-review.googlesource.com/c/go/+/144384/, particularly if we start citing that as precedent for changes like this.

I think that a .Await() or something to get the await JavaScript keyword algorithm available to Go code is a good idea. Await is similar to but not identical to just calling .then(); there's the Promise.resolve() native-ification step too. ^{Related reading: https://www.zhenghao.io/posts/await-vs-promise}

[ianlancetaylor]

CC @golang/js

[earthboundkid]

I'm not sure why this isn't just equivalent to calling .then like this:

func await(awaitable js.Value) (ret js.Value, ok bool) {
        ch := make(chan struct{})
        go func() {
                awaitable.
                        Call("then", js.FuncOf(func(this js.Value, args []js.Value) interface{} {
                                ret = args[0]
                                ok = true
                                close(ch)
                                return nil
                        })).
                        Call("catch", js.FuncOf(func(this js.Value, args []js.Value) interface{} {
                                ret = args[0]
                                ok = false
                                close(ch)
                                return nil
                        }))
        }()
        <-ch
        return
}

(From a project I did in Go WASM.)

Yes, using await and .then are different experiences in JavaScript, but from the Go side, why wouldn't this be sufficient?

[Zxilly]

If we really want such an API, maybe we also need some new APIs like syscall/js.AsyncFuncOf()? Considering the contagious nature of async in js, this might be necessary.

And, as there is no distinction between synchronous and asynchronous functions in Go, we may need additional wrapping to do this.

[jcbhmr]

re @earthboundkid

Yes, using await and .then are different experiences in JavaScript, but from the Go side, why wouldn't this be sufficient?

This is kinda my point. The func await(awaitable) example is experiencably different than the JS await behaviour: it panics if awaitable is not .then()-able or only implements the 2-arg .then() without a .catch() helper. There's quite a few edge cases like that that differ among so many people creating the same helper function that are oh-so-similar but subtly different in panic conditions, error conditions, non-Promise values, properly .Release()-ing the js.Func things, etc.. What I would like to see is a "one good builtin way to do it" to access the JS await keyword's behavior in Go code. And since it's a keyword from the JS language syntax I figured syscall/js is the best place to put it.

[pulsejet]

In case someone comes across this - I recently wrote a few small clean utilities to do exactly this.
https://github.com/named-data/ndnd/blob/d807000cd62d93b42d1407ae528f49e467916617/std/utils/js/promise.go

In my implementation, Await(promise) returns (js.Value, error) which seemed like the most idiomatic API from a Go POV. Similarly, AsyncFunc's return value is (any, error)

Example usage:

// Usage of Await
fetch := js.Global().Get("fetch")
res, err := jsutil.Await(fetch.Invoke(js.ValueOf("/hellp")))
if err != nil {
	// ... handle error
}
// ... handle response

// Usage of AsyncFunc
// my_async(): Promise<void>;
"my_async": jsutil.AsyncFunc(func(this js.Value, p []js.Value) (any, error) {
        res, err := doSomething()
	return js.ValueOf(res), err
}),

So far we've been using this pattern and it has been very intuitive.

[jcbhmr]

Again everyone creates their own variant that's not actually quite identical to the real js await keyword. The Await() method doesn't appear to do the preemptive Promise.resolve() step and panics of there's no .then() or .catch() method lol. It works but it's slightly different from the native way.

Imo it would be best if there was one known good identical-to-js await function or method that brings the await keywords behavior to Go. Similar thing with #72045

This behaviour is already in the standard library for fetch() handling. Imo tidying up that code into a nice await() syscall/js operator method similar to .Equal() would be beneficial for the stdlib and external code as well.

[pulsejet]

The Await() method doesn't appear to do the preemptive Promise.resolve() step and panics of there's no .then() or .catch() method lol.

This is intentional in my case. A useless await in JS is zero cost, but that's not the case with Promise.resolve called from WASM - the cost is small but the panic tells you you're doing something unnecessary.

But (IMHO) I largely agree this does not belong in syscall simply because it's syntax. There's a likely a bunch of syntax sugar (switch comes to mind) that would be convenient but can be easily implemented with existing primitives. This would be nice to have somewhere in a utility library perhaps but it doesn't seem fundamental enough for syscall.

(the only reason I linked the utils file is so that the next person has a quick starting point)