promise

README

go-js-promise

Go WebAssembly utility package for interacting with JavaScript promises, and aiming to have an "idiomatic Go" API.

Documentation on pkg.go.dev.

Show your support

Give a ⭐️ and/or sponsor if this project helped you!

Author

👤 Nicolas Lepage

• Website: https://nicolas.lepage.dev/
• Twitter: @njblepage
• Github: @nlepage

🤝 Contributing

Contributions, issues and feature requests are welcome!
Feel free to check issues page.

📝 License

Copyright © 2021 Nicolas Lepage.
This project is Apache 2.0 licensed.

Documentation

Overview

Package promise is a utility for interacting with JavaScript promises.

All errors returned from this package (except for promise.Any) are of type promise.Reason which can be converted back to js.Value if necessary.

Example

// create a new Promise
p, resolve, reject := promise.New()

go func() {
	time.Sleep(100 * time.Millisecond) // do some asynchronous job...

	if err := error(nil); err != nil {
		reject(err) // reject promise if something went wrong
		return
	}

	// resolve promise if all looks good
	resolve("asynchronous job is done!")
}()

// wait for the promise to resolve or reject
v, err := promise.Await(p)
if err != nil {
	fmt.Printf("error: %#v\n", err.Error())
	return
}

fmt.Println(v)

Output:

asynchronous job is done!

Index

• Constants
• func All(ps []js.Value) ([]js.Value, error)
• func Any(ps []js.Value) (js.Value, error)
• func Await(p js.Value) (js.Value, error)
• func New() (p js.Value, resolve func(interface{}), reject func(interface{}))
• func Race(ps []js.Value) (js.Value, error)
• func Reject(v interface{}) js.Value
• func Resolve(v interface{}) js.Value
• type AggregateError
  • func (err AggregateError) Error() string
  • func (err AggregateError) Errors() []error
• type Reason
  • func (r Reason) Error() string
• type Result
  • func AllSettled(ps []js.Value) []Result
  • func (r Result) Reason() Reason
  • func (r Result) Status() string
  • func (r Result) Value() js.Value

Examples

• Package
• All
• AllSettled
• Any
• Race

Constants

const (
	// Fulfilled is the state value of a resolved promise.
	Fulfilled = "fulfilled"

	// Rejected is the state value of a rejected promise.
	Rejected = "rejected"
)

Functions

func All

func All(ps []js.Value) ([]js.Value, error)

All waits for a given list of promises to be resolved and returns a list of the results.

It returns an error if any of the input promises rejects.

See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all

Example

values, err := promise.All([]js.Value{
	promise.Resolve(1),
	promise.Resolve(2),
	promise.Resolve(3),
})

if err != nil {
	fmt.Printf("error: %#v\n", err.Error())
	return
}

for _, v := range values {
	fmt.Println(v.Int())
}

Output:

1
2
3

func Any

func Any(ps []js.Value) (js.Value, error)

Any returns the result of the first fulfilled promise in a given list of promises.

If no promises in the given list fulfills, then it returns a promise.AggregateError.

See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/any

Example

p1 := promise.Reject("rejected at first!")
p2, resolve2, _ := promise.New()
p3, _, reject3 := promise.New()

time.AfterFunc(200*time.Millisecond, func() { resolve2("resolved at last!") })
time.AfterFunc(100*time.Millisecond, func() { reject3("eventually rejected!") })

v, err := promise.Any([]js.Value{p1, p2, p3})
if err != nil {
	fmt.Printf("error: %#v\n", err.Error())
	return
}

fmt.Println(v.String())

Output:

resolved at last!

func Await

func Await(p js.Value) (js.Value, error)

Await waits for the given Promise to be resolved or rejected.

Similarly to JavaScript's await, if p isn't a Promise, it is returned as the result.

See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await

func New

func New() (p js.Value, resolve func(interface{}), reject func(interface{}))

New creates a JavaScript Promise.

Returns the Promise, and the resolve/reject callback funcs.

See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/Promise

func Race

func Race(ps []js.Value) (js.Value, error)

Race returns the result of the first fulfilled or rejected promise in a given list of promises.

See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/race

Example

p1, resolve1, _ := promise.New()
p2, resolve2, _ := promise.New()

time.AfterFunc(200*time.Millisecond, func() { resolve1("second!") })
time.AfterFunc(100*time.Millisecond, func() { resolve2("first!") })

v, err := promise.Race([]js.Value{p1, p2})
if err != nil {
	fmt.Printf("error: %#v\n", err.Error())
	return
}

fmt.Println(v.String())

Output:

first!

func Reject

func Reject(v interface{}) js.Value

Reject creates a JavaScript Promise rejected with a given value.

See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/reject

func Resolve

func Resolve(v interface{}) js.Value

Resolve creates a JavaScript Promise resolved with a given value.

See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/resolve

Types

type AggregateError

type AggregateError js.Error

AggregateError is a JavaScript object representing an error when several errors need to be wrapped in a single error.

It is returned by promise.Any.

It can be converted back to js.Error if needed.

See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/AggregateError

func (AggregateError) Error

func (err AggregateError) Error() string

Error returns the string property "message" of the error.

func (AggregateError) Errors

func (err AggregateError) Errors() []error

Errors returns the list of errors wrapped by the error.

type Reason

type Reason js.Value

Reason is a JavaScript value a promise was rejected with.

It implements the error interface.

It can be converted back to js.Value if needed.

func (Reason) Error

func (r Reason) Error() string

Error returns the string property "message" of the value if present, a string representation of the value otherwise.

type Result

type Result js.Value

Result is a JavaScript object that describes the outcome of a promise.

func AllSettled

func AllSettled(ps []js.Value) []Result

AllSettled waits for a given list of promises to be fulfilled or rejected.

It returns a list of promise.Result which describes the outcome of each input promises.

See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/allSettled

Example

results := promise.AllSettled([]js.Value{
	promise.Resolve(1),
	promise.Reject(2),
	promise.Resolve(3),
})

for _, r := range results {
	switch r.Status() {
	case "fulfilled":
		fmt.Printf("resolved: %#v\n", r.Value().Int())
	case "rejected":
		fmt.Printf("rejected: %#v\n", r.Reason().Error())
	}
}

Output:

resolved: 1
rejected: "2"
resolved: 3

func (Result) Reason

func (r Result) Reason() Reason

Reason returns the value the promise was rejected with if status is "rejected", js.Undefined() otherwise.

func (Result) Status

func (r Result) Status() string

Status returns the status of the promise, "fulfilled" or "rejected"

func (Result) Value

func (r Result) Value() js.Value

Value returns the result of the promise if status is "fulfilled", js.Undefined() otherwise.