js

package
v0.2.1 Latest Latest
Warning

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

 Go to latest Published: Oct 10, 2023 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package js provides ffi support for JavaScript.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Free 

func Free[T ~uint32](refs ...T)

func Must 

func Must[T any](x T, ok bool) T

func Pointer 

func Pointer[T any](p *T) unsafe.Pointer

func SizeI 

func SizeI[T num.Integer | num.Pointer](v T) (x int32)

func SizeU 

func SizeU[T num.Integer | num.Pointer](v T) (x uint32)

func SliceData 

func SliceData[T any](s []T) unsafe.Pointer

func StringData 

func StringData(s string) unsafe.Pointer

func ThrowCallbackValueNotReturned 

func ThrowCallbackValueNotReturned()

func ThrowInvalidCallbackInvocation 

func ThrowInvalidCallbackInvocation()

Types

type Any 

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

func TryAwait 

func TryAwait[
	T interface{ FromRef(Ref) T },
](
	p Promise[T], exception Any, ok bool,
) (
	value T, err Any, fulfilled bool,
)

TryAwait is a helper function to consume Promises returned from TryXxx functions.

It calls p.Await(true) when ok is true.

func (Any) AsArray 

func (x Any) AsArray() Array[Any]

func (Any) AsFunc 

func (x Any) AsFunc() Func[Any]

func (Any) AsNumber 

func (x Any) AsNumber() Number[float64]

func (Any) AsObject 

func (x Any) AsObject() Object

func (Any) AsString 

func (x Any) AsString() String

func (Any) Free 

func (x Any) Free()

func (Any) FromRef 

func (x Any) FromRef(ref Ref) Any

func (Any) InstanceOf 

func (x Any) InstanceOf(o Ref) bool

func (Any) Once 

func (x Any) Once() Any

func (Any) Ref 

func (x Any) Ref() Ref

type Array 

type Array[T any] struct {
	// contains filtered or unexported fields
}

func NewArray 

func NewArray[T any](sz int) Array[T]

func NewArrayOf 

func NewArrayOf[T any](take bool, elems ...Ref) Array[T]

func (Array[T]) Copy 

func (a Array[T]) Copy(start int, outBuf []Ref) int

func (Array[T]) Fill 

func (a Array[T]) Fill(start int, take bool, elems ...Ref) int

func (Array[T]) Free 

func (a Array[T]) Free()

func (Array[T]) FromRef 

func (a Array[T]) FromRef(ref Ref) Array[T]

func (Array[T]) Length 

func (a Array[T]) Length() int

func (Array[T]) MustFill 

func (a Array[T]) MustFill(start int, take bool, elems ...Ref) Array[T]

func (Array[T]) Nth 

func (a Array[T]) Nth(i int) (Ref, bool)

func (Array[T]) NthBool 

func (a Array[T]) NthBool(i int) (bool, bool)

func (Array[T]) NthNum 

func (a Array[T]) NthNum(i int) (float64, bool)

func (Array[T]) Once 

func (a Array[T]) Once() Array[T]

func (Array[T]) Ref 

func (a Array[T]) Ref() Ref

func (Array[T]) SetNth 

func (a Array[T]) SetNth(i int, take bool, val Ref) bool

func (Array[T]) SetNthBool 

func (a Array[T]) SetNthBool(i int, val bool) bool

func (Array[T]) SetNthNum 

func (a Array[T]) SetNthNum(i int, val float64) bool

func (Array[T]) SetNthString 

func (a Array[T]) SetNthString(i int, s string) bool

func (Array[T]) Slice 

func (a Array[T]) Slice(start, end int) Array[T]

func (Array[T]) SliceFrom 

func (a Array[T]) SliceFrom(start int) Array[T]

type ArrayBuffer 

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

TODO

func (ArrayBuffer) Free 

func (buf ArrayBuffer) Free()

func (ArrayBuffer) FromRef 

func (buf ArrayBuffer) FromRef(ref Ref) ArrayBuffer

func (ArrayBuffer) Once 

func (buf ArrayBuffer) Once() ArrayBuffer

func (ArrayBuffer) Ref 

func (buf ArrayBuffer) Ref() Ref

type ArrayBufferView 

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

TODO

func (ArrayBufferView) Free 

func (v ArrayBufferView) Free()

func (ArrayBufferView) FromRef 

func (v ArrayBufferView) FromRef(ref Ref) ArrayBufferView

func (ArrayBufferView) Once 

func (v ArrayBufferView) Once() ArrayBufferView

func (ArrayBufferView) Ref 

func (v ArrayBufferView) Ref() Ref

type BigInt 

type BigInt[T bigintTypes] struct {
	// contains filtered or unexported fields
}

func NewBigInt 

func NewBigInt[T bigintTypes](value T) BigInt[T]

func (BigInt[T]) Free 

func (b BigInt[T]) Free()

func (BigInt[T]) FromRef 

func (b BigInt[T]) FromRef(ref Ref) BigInt[T]

func (BigInt[T]) Get 

func (b BigInt[T]) Get() T

func (BigInt[T]) Once 

func (b BigInt[T]) Once() BigInt[T]

func (BigInt[T]) Ref 

func (b BigInt[T]) Ref() Ref

func (BigInt[T]) Set 

func (b BigInt[T]) Set(value T) bool

type BigInt64Array 

type BigInt64Array = TypedArray[int64]

type BigUint64Array 

type BigUint64Array = TypedArray[uint64]

type Boolean 

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

func (Boolean) Free 

func (b Boolean) Free()

func (Boolean) FromRef 

func (b Boolean) FromRef(ref Ref) Boolean

func (Boolean) Get 

func (b Boolean) Get() bool

func (Boolean) Once 

func (b Boolean) Once() Boolean

func (Boolean) Ref 

func (b Boolean) Ref() Ref

type CallbackContext 

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

CallbackContext is the context of a function call from JS to Go.

Limitation: At most 16 args (including `this`) are allowed.

The call can be made synchronously (go -> js -> go) and asynchronously (js -> go), the library supports both in one form.

It is user's responsibility to ensure the callback does not call await-like functions such as js.Promise.Await() and yield.Thread() when the js side expects returning result synchronously, and if not so, the js side will get a Promise instead of immediate value.

To return value, call one of .ReturnXxx functions. If none of the return functions was called, it returns js value "undefined". If more than one return functions were called, it returns the value passed in the last .ReturnXxx function.

After returning from the target Go function, All heap references available in the slice returned by .Args() are freed, so users MUST NOT retain any of these references, and if you do want to use after the callback, call Ref.Clone() to make a copy.

func (*CallbackContext) Args 

func (ctx *CallbackContext) Args() []Ref

func (*CallbackContext) Return 

func (ctx *CallbackContext) Return(ref Ref) bool

func (*CallbackContext) ReturnBool 

func (ctx *CallbackContext) ReturnBool(b bool) bool

func (*CallbackContext) ReturnNum 

func (ctx *CallbackContext) ReturnNum(n float64) bool

func (*CallbackContext) ReturnString 

func (ctx *CallbackContext) ReturnString(s string) bool

type CallbackDispatcher 

type CallbackDispatcher interface {
	ffi.CallbackDispatcher[CallbackContext]
}

CallbackDispatcher defines the interface of a js callback dispatcher.

type DataView 

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

TODO

func (DataView) FromRef 

func (v DataView) FromRef(ref Ref) DataView

func (DataView) Ref 

func (v DataView) Ref() Ref

type Executor 

type Executor[T any] struct {
	// contains filtered or unexported fields
}

Executor is a helper for constructing new Promises in js.

TODO: support handling multiple promises simultaneously.

func (*Executor[T]) DispatchCallback 

func (p *Executor[T]) DispatchCallback(targetPC uintptr, ctx *CallbackContext)

DispatchCallback implements CallbackDispatcher.

func (*Executor[T]) Free 

func (p *Executor[T]) Free()

func (*Executor[T]) Reset 

func (p *Executor[T]) Reset(arg T, fn ExecutorFunc[T]) Ref

Reset prepares a new promise for use in js.

type ExecutorFunc 

type ExecutorFunc[T any] func(arg T, this Any) (value, reason Ref, fulfilled bool)

ExecutorFunc defines the go function signature of a promise executor.

type Float32Array 

type Float32Array = TypedArray[float32]

type Float64Array 

type Float64Array = TypedArray[float64]

type FrozenArray 

type FrozenArray[T any] struct {
	// contains filtered or unexported fields
}

TODO

func (FrozenArray[T]) FromRef 

func (a FrozenArray[T]) FromRef(ref Ref) FrozenArray[T]

func (FrozenArray[T]) Ref 

func (a FrozenArray[T]) Ref() Ref

type Func 

type Func[T any] struct {
	// contains filtered or unexported fields
}

func RegisterCallback 

func RegisterCallback[F any, D CallbackDispatcher](dispatcher D, targetPC uintptr) Func[F]

RegisterCallback creates a js function to be called from js.

See CallbackContext for more details.

NOTE: type param D MUST be a pointer type, that is, it either

  • comes with star sign (e.g. *Foo)
  • or being a function (e.g. PromiseCallbackHandleFunc).

func (Func[T]) Call 

func (fn Func[T]) Call(this Ref, take bool, args ...Ref) Ref

Call calls js function fn and returns the heap reference of the js return value.

When free is ture, all args after it are freed after the call.

func (Func[T]) CallBool 

func (fn Func[T]) CallBool(this Ref, take bool, args ...Ref) bool

CallBool calls js function fn and treate the return value as a js boolean.

When free is ture, all args after it are freed after the call.

func (Func[T]) CallNum 

func (fn Func[T]) CallNum(this Ref, take bool, args ...Ref) float64

CallNum calls js function fn and treate the return value as a js number.

When free is ture, all args after it are freed after the call.

func (Func[T]) CallVoid 

func (fn Func[T]) CallVoid(this Ref, take bool, args ...Ref)

CallVoid calls js function fn and discard any return value.

When free is ture, all args after it are freed after the call.

func (Func[T]) Free 

func (fn Func[T]) Free()

func (Func[T]) FromRef 

func (fn Func[T]) FromRef(ref Ref) Func[T]

func (Func[T]) Once 

func (fn Func[T]) Once() Func[T]

func (Func[T]) Ref 

func (fn Func[T]) Ref() Ref

func (Func[T]) Try 

func (fn Func[T]) Try(
	this Ref,
	take bool,
	catch Func[func(err Any, args []Ref) Ref],
	finally Func[func(args []Ref)],
	args ...Ref,
) (Ref, bool)

Try runs the fn in a trycatch block, return heap reference of the result of either fn or catch.

When free is true, all args after it (catch, finally, args...) are freed after the call.

The bool return value indicates whether the try was successful (catch was not called)

type Int8Array 

type Int8Array = TypedArray[int8]

type Int16Array 

type Int16Array = TypedArray[int16]

type Int32Array 

type Int32Array = TypedArray[int32]

type Number 

type Number[T numTypes] struct {
	// contains filtered or unexported fields
}

Number represents a js number living in the heap.

NOTE: This type is defined for code not working directly with imported js functions (using go:wasmimport) and should be avoided whenever possible.

func NewNumber 

func NewNumber[T numTypes](x T) Number[T]

func (Number[T]) Free 

func (b Number[T]) Free()

func (Number[T]) FromRef 

func (b Number[T]) FromRef(ref Ref) Number[T]

func (Number[T]) Get 

func (b Number[T]) Get() T

func (Number[T]) IsInf 

func (b Number[T]) IsInf(sign int) bool

func (Number[T]) IsNaN 

func (b Number[T]) IsNaN() bool

func (Number[T]) Once 

func (b Number[T]) Once() Number[T]

func (Number[T]) Ref 

func (b Number[T]) Ref() Ref

func (*Number[T]) Set 

func (b *Number[T]) Set(value T) bool

type Object 

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

An Object is a reference to a js object.

func New 

func New(constructor Func[Any], args ...Ref) Object

func (Object) BoolProp 

func (o Object) BoolProp(name string) bool

func (Object) BoolPropByString 

func (o Object) BoolPropByString(name String) bool

func (Object) DefineProp 

func (o Object) DefineProp(
	name string,
	flags PropDesc,
	getter Func[func() Any],
	setter Func[func(Any) bool],
) bool

func (Object) DeleteProp 

func (o Object) DeleteProp(name string) bool

func (Object) Free 

func (o Object) Free()

func (Object) FromRef 

func (o Object) FromRef(ref Ref) Object

func (Object) NumProp 

func (o Object) NumProp(name string) float64

func (Object) NumPropByString 

func (o Object) NumPropByString(name String) float64

func (Object) Once 

func (o Object) Once() Object

func (Object) Prop 

func (o Object) Prop(name string) Any

func (Object) PropByString 

func (o Object) PropByString(name String) Any

func (Object) PropDesc 

func (o Object) PropDesc(name string) PropDesc

func (Object) Prototype 

func (o Object) Prototype() (proto Object, hasPrototype bool)

func (Object) Ref 

func (o Object) Ref() Ref

func (Object) SetBoolProp 

func (o Object) SetBoolProp(name string, val bool) bool

func (Object) SetBoolPropByString 

func (o Object) SetBoolPropByString(s String, val bool) bool

func (Object) SetNumProp 

func (o Object) SetNumProp(name string, val float64) bool

func (Object) SetNumPropByString 

func (o Object) SetNumPropByString(prop String, val float64) bool

func (Object) SetProp 

func (o Object) SetProp(name string, free bool, val Ref) bool

func (Object) SetPropByString 

func (o Object) SetPropByString(prop String, free bool, val Ref) bool

func (Object) SetPrototype 

func (o Object) SetPrototype(free bool, proto Ref) bool

SetPrototype sets o's prototype to proto

When free is ture, proto is freed after the call.

func (Object) SetStringProp 

func (o Object) SetStringProp(name, val string) bool

func (Object) SetStringPropByString 

func (o Object) SetStringPropByString(name String, free bool, val String) bool

func (Object) StringProp 

func (o Object) StringProp(name string) String

func (Object) StringPropByString 

func (o Object) StringPropByString(name String) String

type ObservableArray 

type ObservableArray[T any] struct {
	// contains filtered or unexported fields
}

TODO

func (ObservableArray[T]) FromRef 

func (a ObservableArray[T]) FromRef(ref Ref) ObservableArray[T]

func (ObservableArray[T]) Ref 

func (a ObservableArray[T]) Ref() Ref

type Promise 

type Promise[T interface{ FromRef(Ref) T }] struct {
	// contains filtered or unexported fields
}

func NewRejectedPromise 

func NewRejectedPromise[
	T interface{ FromRef(Ref) T },
](reason Ref) Promise[T]

func NewResolvedPromise 

func NewResolvedPromise[
	T interface{ FromRef(Ref) T },
](data Ref) Promise[T]

func (Promise[T]) Await 

func (p Promise[T]) Await(take bool) (value T, err Any, fulfilled bool)

Await works like `await`

When take is true, it frees the Promise p from the application heap.

func (Promise[T]) Free 

func (p Promise[T]) Free()

func (Promise[T]) FromRef 

func (p Promise[T]) FromRef(ref Ref) Promise[T]

func (Promise[T]) MustAwait added in v0.2.1 

func (p Promise[T]) MustAwait(take bool) T

func (Promise[T]) Once 

func (p Promise[T]) Once() Promise[T]

func (Promise[T]) Ref 

func (p Promise[T]) Ref() Ref

func (Promise[T]) Then 

func (p Promise[T]) Then(onfulfilled, onrejected Func[func(Ref)], onfinally Func[func()]) Promise[T]

Then calls Promise.then(onfulfilled, onrejected) and if onfinally is not undefined/null value, call Promise.finally(onfinally).

NOTE: It is generally discouraged to use this function for callbacks to Go code.

type PropDesc 

type PropDesc uint32
const (
	PropDesc_exists       PropDesc = 1 << iota
	PropDesc_writable              //
	PropDesc_configurable          //
	PropDesc_enumerable            //
	PropDesc_getter                //
	PropDesc_setter                //
)

type Record 

type Record[T any] struct {
	// contains filtered or unexported fields
}

TODO

func (Record[T]) Free 

func (r Record[T]) Free()

func (Record[T]) FromRef 

func (r Record[T]) FromRef(ref Ref) Record[T]

func (Record[T]) Once 

func (r Record[T]) Once() Record[T]

func (Record[T]) Ref 

func (r Record[T]) Ref() Ref

type Ref 

type Ref bindings.Ref
const (
	Undefined   Ref = iota // undefined
	Null                   // null
	Zero                   // 0
	False                  // false
	True                   // true
	NaN                    // NaN
	Inf                    // Infinity
	NegativeInf            // -Infinity
	Global                 // globalThis

)

func Bool 

func Bool(b bool) Ref

func (Ref) Any 

func (r Ref) Any() Any

func (Ref) Clone 

func (r Ref) Clone() Ref

Clone returns a new heap reference to the same object referenced by r.

func (Ref) Falsy 

func (r Ref) Falsy() bool

Falsy returns true when r is the reference to one of following values:

  • Undefined
  • Null
  • 0
  • False

Otherwise, it returns false.

func (Ref) Free 

func (r Ref) Free()

Free the referenced js value.

func (Ref) Once 

func (r Ref) Once() Ref

func (Ref) Truthy 

func (r Ref) Truthy() bool

Truthy returns true when r.Falsy() returns false.

func (Ref) Undefined 

func (r Ref) Undefined() bool

type SharedArrayBuffer 

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

TODO

func (SharedArrayBuffer) Free 

func (buf SharedArrayBuffer) Free()

func (SharedArrayBuffer) FromRef 

func (buf SharedArrayBuffer) FromRef(ref Ref) SharedArrayBuffer

func (SharedArrayBuffer) Once 

func (buf SharedArrayBuffer) Once() SharedArrayBuffer

func (SharedArrayBuffer) Ref 

func (buf SharedArrayBuffer) Ref() Ref

type String 

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

A String is a reference to a javascript string.

func NewString 

func NewString(s string) String

NewString creates a js string for the string, return the reference to the created string.

func (String) Append 

func (s String) Append(ss ...string) String

func (String) AppendString added in v0.2.1 

func (s String) AppendString(take bool, ss ...String) String

func (String) Equals 

func (s String) Equals(other string) bool

func (String) Free 

func (s String) Free()

func (String) FromRef 

func (s String) FromRef(ref Ref) String

func (String) Len 

func (s String) Len() int

Len returns the utf-8 length of the js string.

func (String) Once 

func (s String) Once() String

func (String) Prepend 

func (s String) Prepend(ss ...string) String

func (String) PrependString added in v0.2.1 

func (s String) PrependString(take bool, ss ...String) String

func (String) Read 

func (s String) Read(buf []byte) int

Read encodes the js string to buf (UTF-8 encoding) and returns the count of bytes encoded.

func (String) Ref 

func (s String) Ref() Ref

type TypedArray 

type TypedArray[T elem] struct {
	// contains filtered or unexported fields
}

func NewTypedArray 

func NewTypedArray[T elem](sz int) TypedArray[T]

func NewTypedArrayOf 

func NewTypedArrayOf[T elem](elems ...T) TypedArray[T]

func (TypedArray[T]) Buffer 

func (a TypedArray[T]) Buffer(take bool) Ref

func (TypedArray[T]) ByteLength 

func (a TypedArray[T]) ByteLength() int

func (TypedArray[T]) ByteOffset 

func (a TypedArray[T]) ByteOffset() int

func (TypedArray[T]) Copy 

func (a TypedArray[T]) Copy(start int, outBuf []T) int

func (TypedArray[T]) Fill 

func (a TypedArray[T]) Fill(start int, elems ...T) int

func (TypedArray[T]) Free 

func (a TypedArray[T]) Free()

func (TypedArray[T]) FromArrayBuffer 

func (a TypedArray[T]) FromArrayBuffer(take bool, buf ArrayBuffer) TypedArray[T]

func (TypedArray[T]) FromRef 

func (a TypedArray[T]) FromRef(ref Ref) TypedArray[T]

func (TypedArray[T]) FromSharedArrayBuffer 

func (a TypedArray[T]) FromSharedArrayBuffer(take bool, buf SharedArrayBuffer) TypedArray[T]

func (TypedArray[T]) Length 

func (a TypedArray[T]) Length() int

func (TypedArray[T]) MustFill 

func (a TypedArray[T]) MustFill(start int, elems ...T) TypedArray[T]

func (TypedArray[T]) Nth 

func (a TypedArray[T]) Nth(i int) (T, bool)

func (TypedArray[T]) Once 

func (a TypedArray[T]) Once() TypedArray[T]

func (TypedArray[T]) Ref 

func (a TypedArray[T]) Ref() Ref

func (TypedArray[T]) Set 

func (a TypedArray[T]) Set(other TypedArray[T]) TypedArray[T]

func (TypedArray[T]) SetNth 

func (a TypedArray[T]) SetNth(i int, val T) bool

func (TypedArray[T]) Slice 

func (a TypedArray[T]) Slice(start, end int) TypedArray[T]

func (TypedArray[T]) SliceFrom 

func (a TypedArray[T]) SliceFrom(start int) TypedArray[T]

type Uint8Array 

type Uint8Array = TypedArray[uint8]

type Uint8ClampedArray 

type Uint8ClampedArray = TypedArray[uint8]

type Uint16Array 

type Uint16Array = TypedArray[uint16]

type Uint32Array 

type Uint32Array = TypedArray[uint32]

type UntypedCallback 

type UntypedCallback func(args []Ref)

UntypedCallback dispatches js callbacks without resolving argument types.

By convension, args[0] refers to the js `this` context.

func (UntypedCallback) DispatchCallback 

func (fn UntypedCallback) DispatchCallback(_ uintptr, ctx *CallbackContext)

DispatchCallback implements CallbackDispatcher.

func (UntypedCallback) Register 

func (fn UntypedCallback) Register() Func[func([]Ref)]

Register registers this function to js and return the reference to that js function.

type Void 

type Void struct{}

func (Void) Free 

func (Void) Free()

func (Void) FromRef 

func (Void) FromRef(Ref) Void

func (Void) Once 

func (Void) Once() Void

func (Void) Ref 

func (Void) Ref() Ref

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.