syscall/js: Add new convenient functions

[pjebs]

Add 3 new JS functions that are common and make them idiomatic Go in usage:

• New2
• Invoke2
• Call2

[agnivade]

Any new API addition needs to be supported by requirements which will benefit a wide number of users using the package.

Can you please outline your reasoning behind these new methods? When should the user call Invoke vs Invoke2?

Go usually believes in one way of doing things, so diverging the API at this point does not seem to overshadow the benefit gained by introducing this new API.

I believe the panic was deliberately written for a reason, but I cannot recall it at the moment.

[pjebs]

Let me explain:

A primer for non-JS developers:

In JS, the constructor (New in syscall/js), and instance methods (Invoke/Call) of JS objects can throw Exceptions. This package converts the thrown Exceptions to panics of type Error. There is usually nothing "exceptional" about these thrown exceptions. They are better suited to be treated as a returned error value, as per @robpike's reasoning for returning error values instead of throwing Exceptions since the early days of Go.

Reasoning:

1. The syscall/js API was directly based on the gopherjs project, to which I contribute to so I know well.
2. The New2, Invoke2 and Call2 functions convert the thrown Exceptions to idiomatic Go.
3. The addition of these new functions will encourage people to use them rather than work with panics (non-idiomatic). This is a benefit!
4. The naming convention (--2) does not mean "alternative to ...". (Even though they can be thought of as such). It means they return 2 return values, and are 'almost' analogous to the naming convention found in the standard library: eg https://golang.org/pkg/reflect/#Value.Slice3
5. Sometimes New, Invoke and Call panic for other reasons (these are documented in godoc). They are not effected by this proposal and the behaviour will remain the same.

[pjebs]

func errorwrap(v Value)  (_ Value, rErr error) {
    defer func() {
        if e := recover(); e != nil {
            err, ok := e.(*Error)
            if !ok {
                panic(e)
            }
            rErr = err
        }
    }()
    return v, nil
}

func (v Value) New2(args ...interface{}) (Value, error) {
    return errorwrap(v.New(args...))
}

func (v Value) Call2(name string, args ...interface{}) (Value, error) {
    return errorwrap(v.Call(name, args...))
}

func (v Value) Invoke2(args ...interface{}) (Value, error) {
    return errorwrap(v.Invoke(args...))
}

[pjebs]

Any progress on this issue?