docs: Document unexported functions

Some unexported functions are non-trivial and may be confusing. This
commit clarifies their use.
master
Chan Wen Xu 2021-03-21 20:29:31 +07:00
parent ad5b341b1e
commit 37088bf382
Signed by untrusted user: chanbakjsd
GPG Key ID: 7E9A74B1B07A7558
3 changed files with 16 additions and 0 deletions

@ -16,6 +16,10 @@ type goThrowable struct {
Error js.Value `wasm:"error"` Error js.Value `wasm:"error"`
} }
// toJSFunc takes a reflect.Value of a Go function and converts it to a JS function that:
// Errors if the parameter types do not conform to the Go function signature,
// Throws an error if the last returned value is an error and is non-nil,
// Return an array if there's multiple non-error return values.
func toJSFunc(x reflect.Value) js.Value { func toJSFunc(x reflect.Value) js.Value {
funcType := x.Type() funcType := x.Type()
var hasError bool var hasError bool
@ -53,6 +57,8 @@ func toJSFunc(x reflect.Value) js.Value {
var jsValueType = reflect.TypeOf(js.Value{}) var jsValueType = reflect.TypeOf(js.Value{})
// conformJSValueToType attempts to convert the provided JS values to reflect.Values that match the
// types expected for the parameters of funcType.
func conformJSValueToType(funcType reflect.Type, this js.Value, values []js.Value) ([]reflect.Value, error) { func conformJSValueToType(funcType reflect.Type, this js.Value, values []js.Value) ([]reflect.Value, error) {
if funcType.NumIn() == 0 { if funcType.NumIn() == 0 {
if len(values) != 0 { if len(values) != 0 {
@ -62,6 +68,7 @@ func conformJSValueToType(funcType reflect.Type, this js.Value, values []js.Valu
} }
if funcType.In(0) == jsValueType { if funcType.In(0) == jsValueType {
// If the first parameter is a js.Value, it is assumed to be the value of `this`.
values = append([]js.Value{this}, values...) values = append([]js.Value{this}, values...)
} }
@ -88,6 +95,10 @@ func conformJSValueToType(funcType reflect.Type, this js.Value, values []js.Valu
return in, nil return in, nil
} }
// returnValue wraps returned values by Go in a JS-friendly way.
// If there are no returned values, it returns undefined.
// If there is exactly one, it returns the JS equivalent.
// If there is more than one, it returns an array containing the JS equivalent of every returned value.
func returnValue(x []reflect.Value) js.Value { func returnValue(x []reflect.Value) js.Value {
switch len(x) { switch len(x) {
case 0: case 0:

@ -5,6 +5,8 @@ import (
"syscall/js" "syscall/js"
) )
// FromJSValue converts a given js.Value to the Go equivalent.
// The new value of 'out' is undefined if FromJSValue returns an error.
func FromJSValue(x js.Value, out interface{}) error { func FromJSValue(x js.Value, out interface{}) error {
// TODO // TODO
return fmt.Errorf("unimplemented") return fmt.Errorf("unimplemented")

@ -71,6 +71,7 @@ func ToJSValue(x interface{}) js.Value {
} }
} }
// toJSArray converts the provided array or slice to a JS array.
func toJSArray(x reflect.Value) js.Value { func toJSArray(x reflect.Value) js.Value {
arrayConstructor, err := Global().Get("Array") arrayConstructor, err := Global().Get("Array")
if err != nil { if err != nil {
@ -85,6 +86,7 @@ func toJSArray(x reflect.Value) js.Value {
return array return array
} }
// mapToJSObject converts the provided map to a JS object.
func mapToJSObject(x reflect.Value) js.Value { func mapToJSObject(x reflect.Value) js.Value {
objectConstructor, err := Global().Get("Object") objectConstructor, err := Global().Get("Object")
if err != nil { if err != nil {
@ -134,6 +136,7 @@ func mapToJSObject(x reflect.Value) js.Value {
return obj return obj
} }
// structToJSObject converts a struct to a JS object.
func structToJSObject(x reflect.Value) js.Value { func structToJSObject(x reflect.Value) js.Value {
objectConstructor, err := Global().Get("Object") objectConstructor, err := Global().Get("Object")
if err != nil { if err != nil {