jsbuiltin

README

jsbuiltin - Built-in JavaScript functions for GopherJS

JavaScript has a small number of built-in functions to handle some common day-to-day tasks. This package providers wrappers around some of these functions for use in GopherJS.

It is worth noting that in many cases, using Go's equivalent functionality (such as that found in the net/url package) may be preferable to using this package, and will be a necessity any time you wish to share functionality between front-end and back-end code.

What is supported?

Not all JavaScript built-in functions make sense or are useful in a Go environment. The table below shows each of the JavaScript built-in functions, and its current state in this package.

Name	Supported	Comment
eval()	--
uneval()	--
isFinite()	yes
isNaN()	yes
parseFloat()	TODO?	See note below
parseInt()	TODO?	See note below
decodeURI()	yes
decodeURIComponent()	yes
encodeURI()	yes
encodeURIComponent()	yes
escape()	--	deprecated circa 2000
Number()	--	See note below
String()	--	Use js.Object.String()
unescape()	--	deprecated circa 2000
typeof operator	yes
instanceof operator	yes

Notes on unmplemented functions

• eval(): Is there ever a need to eval JS code from within Go?
• Number(): This requires handling a bunch of corner cases which don't normally exist in a strictly typed language such as Go. It seems that anyone with a legitimate need for this function probably needs to write their own wrapper to handle the cases that matter to them.
• parseInt() and parseFloat(): These could be added, but doing so will require answering some questions about the interfce. JavaScript has effectively two relevant data types (int and float) where Go has has 12. Deciding how to map JS's parseInt() to Go's (u?)int(8|16|32|64) types, and JS's parseFloat() Go's float(32|64) or complex(64|128) needs to be considered, as well as how to handle error cases (Go doesn't have a NaN type, so any NaN result probably needs to be converted to a proper Go error). If this matters to you, comments and/or PRs are welcome.

Installation and Usage

Get or update this package and dependencies with:

go get -u -d -tags=js github.com/gopherjs/jsbuiltin

Basic usage example

This is a modified version of the Pet example in the main GopherJS documentation, to accept and return URI-encoded pet names using the jsbuiltin package.

package main

import (
	"github.com/gopherjs/gopherjs/js"
	"github.com/gopherjs/jsbuiltin"
)

func main() {
	js.Global.Set("pet", map[string]interface{}{
		"New": New,
	})
}

type Pet struct {
	name string
}

func New(name string) *js.Object {
	return js.MakeWrapper(&Pet{name})
}

func (p *Pet) Name() string {
	return jsbuiltin.EncodeURIComponent(p.name)
}

func (p *Pet) SetName(uriComponent string) error {
	name, err := jsbuiltin.DecodeURIComponent(uriComponent)
	if err != nil {
		// Malformed UTF8 in uriComponent
		return err
	}
	p.name = name
	return nil
}

Documentation

Overview

Package jsbuiltin provides minimal wrappers around some JavasScript built-in functions.

Index

• Constants
• func DecodeURI(uri string) (raw string, err error)
• func DecodeURIComponent(uri string) (raw string, err error)
• func EncodeURI(uri string) string
• func EncodeURIComponent(uri string) string
• func In(key string, obj *js.Object) (ok bool, err error)
• func InstanceOf(value interface{}, object *js.Object) bool
• func IsFinite(value interface{}) bool
• func IsNaN(value interface{}) bool
• func TypeOf(value interface{}) string

Constants

const (
	TypeUndefined = "undefined"
	TypeNull      = "null"
	TypeObject    = "object"
	TypeBoolean   = "boolean"
	TypeNumber    = "number"
	TypeString    = "string"
	TypeFunction  = "function"
	TypeSymbol    = "symbol"
)

Type constants represent the JavaScript builtin types, which may be returned by TypeOf().

Functions

func DecodeURI

func DecodeURI(uri string) (raw string, err error)

DecodeURI decodes a Uniform Resource Identifier (URI) previously created by EncodeURI() or by a similar routine. If the underlying JavaScript function throws an error, it is returned as an error.

func DecodeURIComponent

func DecodeURIComponent(uri string) (raw string, err error)

DecodeURIComponent decodes a Uniform Resource Identifier (URI) component previously created by EncodeURIComponent() or by a similar routine. If the underlying JavaScript function throws an error, it is returned as an error.

func EncodeURI

func EncodeURI(uri string) string

EncodeURI encodes a Uniform Resource Identifier (URI) by replacing each instance of certain characters by one, two, three, or four escape sequences representing the UTF-8 encoding of the character (will only be four escape sequences for characters composed of two "surrogate" characters).

func EncodeURIComponent

func EncodeURIComponent(uri string) string

EncodeURIComponent encodes a Uniform Resource Identifier (URI) component by replacing each instance of certain characters by one, two, three, or four escape sequences representing the UTF-8 encoding of the character (will only be four escape sequences for characters composed of two "surrogate" characters).

func In

func In(key string, obj *js.Object) (ok bool, err error)

In returns true if key is a member of obj. An error is returned if obj is not a JavaScript object.

func InstanceOf

func InstanceOf(value interface{}, object *js.Object) bool

InstanceOf returns true if value is an instance of object according to the built-in 'instanceof' operator. `object` must be a *js.Object representing a javascript constructor function.

func IsFinite

func IsFinite(value interface{}) bool

IsFinite determines whether the passed value is a finite number, and returns true if it is. If needed, the parameter is first converted to a number.

func IsNaN

func IsNaN(value interface{}) bool

IsNaN determines whether a value is NaN (Not-a-Number) or not. A return value of true indicates the input value is considered NaN by JavaScript.

func TypeOf

func TypeOf(value interface{}) string

TypeOf returns the JavaScript type of the passed value