js

Documentation

Overview

Package js is a drop-in replacement for syscall/js that provides identical behavior in a WebAssembly environment, and useful non-functional behavior outside of WebAssembly.

To use it, simply import this package instead of "syscall/js" and use it in exactly the same way. Your code will compile targeting either wasm or non-wasm environments. In wasm, the functionality is exactly the same, the calls and types are delegated directly to "syscall/js". The compiler will optimize away virtually (if not literally) all of the overhead associated with this aliasing. When run outside of wasm, appropriate functionality indicates that the environment is not availble: All js.Value instances are undefined. Global(), Value.Get() always return undefined. Value.Call(), FuncOf() and other such functions will panic. Value.Truthy() will always return false. For example, Global().Truthy() can be used to determine if the js environment is functional.

Rationale: Since syscall/js is only available when the GOOS is "js", this means programs which run server-side cannot access that package and will fail to compile. Since Vugu components are inherently closely integrated with browsers and may often need to do things like declare variables of type js.Value, this is a problem for components which are rendered not only in wasm client-side but also server-side. Build tags can be used to provide multiple implementations of a components but this can become tedious.

Usually what you want is that the majority of your code which is not js-specific can be written once and execute in the browser or on the server, and the relatively small amount of functionality that is uses "js" will compile properly in both environments but just not be executed on the server. Or allow for if statements to easily disable functionality not available server-side. That's what this package provides.

Index

• Constants
• func CopyBytesToGo(dst []byte, src Value) int
• func CopyBytesToJS(dst Value, src []byte) int
• type Error
  • func (e Error) Error() string
• type Func
  • func FuncOf(fn func(this Value, args []Value) any) Func
  • func (c Func) Release()
• type Type
  • func (t Type) String() string
• type Value
  • func Global() Value
  • func Null() Value
  • func Undefined() Value
  • func ValueOf(x any) Value
  • func (v Value) Bool() bool
  • func (v Value) Call(m string, args ...any) Value
  • func (v Value) Delete(p string)
  • func (v Value) Equal(w Value) bool
  • func (v Value) Float() float64
  • func (v Value) Get(p string) Value
  • func (v Value) Index(i int) Value
  • func (v Value) InstanceOf(t Value) bool
  • func (v Value) Int() int
  • func (v Value) Invoke(args ...any) Value
  • func (v Value) IsNaN() bool
  • func (v Value) IsNull() bool
  • func (v Value) IsUndefined() bool
  • func (v Value) Length() int
  • func (v Value) New(args ...any) Value
  • func (v Value) Set(p string, x any)
  • func (v Value) SetIndex(i int, x any)
  • func (v Value) String() string
  • func (v Value) Truthy() bool
  • func (v Value) Type() Type
• type ValueError
  • func (e *ValueError) Error() string

Constants

const (
	TypeUndefined = iota
	TypeNull
	TypeBoolean
	TypeNumber
	TypeString
	TypeSymbol
	TypeObject
	TypeFunction
)

This is a syscall/js placeholder.

Functions

func CopyBytesToGo

func CopyBytesToGo(dst []byte, src Value) int

CopyBytesToGo copies bytes from src to dst. It panics if src is not a Uint8Array or Uint8ClampedArray. It returns the number of bytes copied, which will be the minimum of the lengths of src and dst.

This is a syscall/js placeholder.

func CopyBytesToJS

func CopyBytesToJS(dst Value, src []byte) int

CopyBytesToJS copies bytes from src to dst. It panics if dst is not a Uint8Array or Uint8ClampedArray. It returns the number of bytes copied, which will be the minimum of the lengths of src and dst.

This is a syscall/js placeholder.

Types

type Error

type Error struct {
	Value
}

Error wraps a JavaScript error.

This is a syscall/js placeholder.

func (Error) Error

func (e Error) Error() string

Error implements the error interface.

This is a syscall/js placeholder.

type Func

type Func struct {
	Value // the JavaScript function that invokes the Go function
}

Func is a wrapped Go function to be called by JavaScript.

This is a syscall/js placeholder.

func FuncOf

func FuncOf(fn func(this Value, args []Value) any) Func

FuncOf returns a function to be used by JavaScript.

The Go function fn is called with the value of JavaScript's "this" keyword and the arguments of the invocation. The return value of the invocation is the result of the Go function mapped back to JavaScript according to ValueOf.

Invoking the wrapped Go function from JavaScript will pause the event loop and spawn a new goroutine. Other wrapped functions which are triggered during a call from Go to JavaScript get executed on the same goroutine.

As a consequence, if one wrapped function blocks, JavaScript's event loop is blocked until that function returns. Hence, calling any async JavaScript API, which requires the event loop, like fetch (http.Client), will cause an immediate deadlock. Therefore a blocking function should explicitly start a new goroutine.

Func.Release must be called to free up resources when the function will not be invoked any more.

This is a syscall/js placeholder.

func (Func) Release

func (c Func) Release()

Release frees up resources allocated for the function. The function must not be invoked after calling Release. It is allowed to call Release while the function is still running.

This is a syscall/js placeholder.

type Type

type Type int

Type represents the JavaScript type of a Value.

This is a syscall/js placeholder.

func (Type) String

func (t Type) String() string

This is a syscall/js placeholder.

type Value

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

Value represents a JavaScript value. The zero value is the JavaScript value "undefined". Values can be checked for equality with the Equal method.

This is a syscall/js placeholder.

func Global

func Global() Value

Global returns the JavaScript global object, usually "window" or "global".

This is a syscall/js placeholder.

func Null

func Null() Value

Null returns the JavaScript value "null".

This is a syscall/js placeholder.

func Undefined

func Undefined() Value

Undefined returns the JavaScript value "undefined".

This is a syscall/js placeholder.

func ValueOf

func ValueOf(x any) Value

ValueOf returns x as a JavaScript value:

| Go                     | JavaScript             |
| ---------------------- | ---------------------- |
| js.Value               | [its value]            |
| js.Func                | function               |
| nil                    | null                   |
| bool                   | boolean                |
| integers and floats    | number                 |
| string                 | string                 |
| []interface{}          | new array              |
| map[string]interface{} | new object             |

Panics if x is not one of the expected types.

This is a syscall/js placeholder.

func (Value) Bool

func (v Value) Bool() bool

Bool returns the value v as a bool. It panics if v is not a JavaScript boolean.

This is a syscall/js placeholder.

func (Value) Call

func (v Value) Call(m string, args ...any) Value

Call does a JavaScript call to the method m of value v with the given arguments. It panics if v has no method m. The arguments get mapped to JavaScript values according to the ValueOf function.

This is a syscall/js placeholder.

func (Value) Delete

func (v Value) Delete(p string)

Delete deletes the JavaScript property p of value v. It panics if v is not a JavaScript object.

This is a syscall/js placeholder.

func (Value) Equal

func (v Value) Equal(w Value) bool

Equal reports whether v and w are equal according to JavaScript's === operator.

This is a syscall/js placeholder.

func (Value) Float

func (v Value) Float() float64

Float returns the value v as a float64. It panics if v is not a JavaScript number.

This is a syscall/js placeholder.

func (Value) Get

func (v Value) Get(p string) Value

Get returns the JavaScript property p of value v. It panics if v is not a JavaScript object.

This is a syscall/js placeholder.

func (Value) Index

func (v Value) Index(i int) Value

Index returns JavaScript index i of value v. It panics if v is not a JavaScript object.

This is a syscall/js placeholder.

func (Value) InstanceOf

func (v Value) InstanceOf(t Value) bool

InstanceOf reports whether v is an instance of type t according to JavaScript's instanceof operator.

This is a syscall/js placeholder.

func (Value) Int

func (v Value) Int() int

Int returns the value v truncated to an int. It panics if v is not a JavaScript number.

This is a syscall/js placeholder.

func (Value) Invoke

func (v Value) Invoke(args ...any) Value

Invoke does a JavaScript call of the value v with the given arguments. It panics if v is not a JavaScript function. The arguments get mapped to JavaScript values according to the ValueOf function.

This is a syscall/js placeholder.

func (Value) IsNaN

func (v Value) IsNaN() bool

IsNaN reports whether v is the JavaScript value "NaN".

This is a syscall/js placeholder.

func (Value) IsNull

func (v Value) IsNull() bool

Null returns the JavaScript value "null".

This is a syscall/js placeholder.

func (Value) IsUndefined

func (v Value) IsUndefined() bool

IsUndefined reports whether v is the JavaScript value "undefined".

This is a syscall/js placeholder.

func (Value) Length

func (v Value) Length() int

Length returns the JavaScript property "length" of v. It panics if v is not a JavaScript object.

This is a syscall/js placeholder.

func (Value) New

func (v Value) New(args ...any) Value

New uses JavaScript's "new" operator with value v as constructor and the given arguments. It panics if v is not a JavaScript function. The arguments get mapped to JavaScript values according to the ValueOf function.

This is a syscall/js placeholder.

func (Value) Set

func (v Value) Set(p string, x any)

Set sets the JavaScript property p of value v to ValueOf(x). It panics if v is not a JavaScript object.

This is a syscall/js placeholder.

func (Value) SetIndex

func (v Value) SetIndex(i int, x any)

SetIndex sets the JavaScript index i of value v to ValueOf(x). It panics if v is not a JavaScript object.

This is a syscall/js placeholder.

func (Value) String

func (v Value) String() string

String returns the value v as a string. String is a special case because of Go's String method convention. Unlike the other getters, it does not panic if v's Type is not TypeString. Instead, it returns a string of the form "<T>" or "<T: V>" where T is v's type and V is a string representation of v's value.

This is a syscall/js placeholder.

func (Value) Truthy

func (v Value) Truthy() bool

Truthy returns the JavaScript "truthiness" of the value v. In JavaScript, false, 0, "", null, undefined, and NaN are "falsy", and everything else is "truthy". See https://developer.mozilla.org/en-US/docs/Glossary/Truthy.

This is a syscall/js placeholder.

func (Value) Type

func (v Value) Type() Type

Type returns the JavaScript type of the value v. It is similar to JavaScript's typeof operator, except that it returns TypeNull instead of TypeObject for null.

This is a syscall/js placeholder.

type ValueError

type ValueError struct {
	Method string
	Type   Type
}

A ValueError occurs when a Value method is invoked on a Value that does not support it. Such cases are documented in the description of each method.

This is a syscall/js placeholder.

func (*ValueError) Error

func (e *ValueError) Error() string

This is a syscall/js placeholder.