js-sys: Expose bindings to ALL the global JS things

[fitzgen]

This is about exposing ALL of the globally available JS APIs through the js-sys crate. Things that are guaranteed by the ECMAScript standard, not Web/Node/etc APIs.

A good overview/list/documentation of these APIs is available here and I've also made a checklist below. As we implement bindings for these APIs, I will check them off.

How to Implement New Bindings

• Comment here saying which thing you are going to make bindings for (so that we don't accidentally duplicate effort). I'll add your username next to the checkbox item.

• Open the MDN page for the relevant JS API.

• Open crates/js-sys/src/lib.rs in your editor; this is the file where we are implementing the bindings.

• Follow the instructions in crates/js-sys/src/lib.rs about how to add new bindings:

  wasm-bindgen/crates/js-sys/src/lib.rs

  Lines 28 to 44 in aa348f9

  	// When adding new imports:
  	//
  	// * Keep imports in alphabetical order.
  	//
  	// * Rename imports with `js_name = ...` according to the note about `camelCase`
  	// and `snake_case` in the module's documentation above.
  	//
  	// * Include the one sentence summary of the import from the MDN link in the
  	// module's documentation above, and the MDN link itself.
  	//
  	// * If a function or method can throw an exception, make it catchable by adding
  	// `#[wasm_bindgen(catch)]`.
  	//
  	// * Add a new `#[test]` into the appropriate file in the
  	// `tests/all/js_globals/` directory. If the imported function or
  	// method can throw an exception, make sure to also add test coverage
  	// for that case.

• Add a test for the new binding to crates/js-sys/tests/wasm/MyType.rs

• Run the JS global API bindings tests with cargo test -p js-sys --target wasm32-unknown-unknown

• Send a pull request! 😸

---

Depends on this PR for the initial skeleton and infrastructure:

• Expose objects and functions from the JavaScript global scope #274

---

All String bindings depend on:

• Cannot use JS strings without copying them into wasm memory #287

---

• Array

  • Array.length (@robertDurst)

  • Array.from()

  • Array.isArray()

  • Array.of()

  • Array.prototype.concat()

  • Array.prototype.copyWithin()

  • Array.prototype.entries()

  • Array.prototype.every()

  • Array.prototype.fill()

  • Array.prototype.filter()

  • Array.prototype.find()

  • Array.prototype.findIndex()

  • Array.prototype.forEach()

  • Array.prototype.includes()

  • Array.prototype.indexOf()

  • Array.prototype.join()

  • Array.prototype.keys()

  • Array.prototype.lastIndexOf()

  • Array.prototype.map()

  • Array.prototype.pop() (@sepiropht)

  • Array.prototype.push()

  • Array.prototype.reduce()

  • Array.prototype.reduceRight()

  • Array.prototype.reverse()

  • Array.prototype.shift()

  • Array.prototype.slice()

  • Array.prototype.some()

  • Array.prototype.sort()

  • Array.prototype.splice()

  • Array.prototype.toLocaleString()

  • Array.prototype.toString()

  • Array.prototype.unshift()

  • Array.prototype.values()

• ArrayBuffer

  • ArrayBuffer.prototype.byteLength

  • ArrayBuffer.isView()

  • ArrayBuffer.prototype.slice()

• Boolean

• DataView

  • DataView.prototype.buffer

  • DataView.prototype.byteLength

  • DataView.prototype.byteOffset

  • DataView.prototype.getFloat32()

  • DataView.prototype.getFloat64()

  • DataView.prototype.getInt16()

  • DataView.prototype.getInt32()

  • DataView.prototype.getInt8()

  • DataView.prototype.getUint16()

  • DataView.prototype.getUint32()

  • DataView.prototype.getUint8()

  • DataView.prototype.setFloat32()

  • DataView.prototype.setFloat64()

  • DataView.prototype.setInt16()

  • DataView.prototype.setInt32()

  • DataView.prototype.setInt8()

  • DataView.prototype.setUint16()

  • DataView.prototype.setUint32()

  • DataView.prototype.setUint8()

• Date

  • Date.UTC()

  • Date.now()

  • Date.parse()

  • Date.prototype.getDate()

  • Date.prototype.getDay()

  • Date.prototype.getFullYear()

  • Date.prototype.getHours()

  • Date.prototype.getMilliseconds()

  • Date.prototype.getMinutes()

  • Date.prototype.getMonth()

  • Date.prototype.getSeconds()

  • Date.prototype.getTime()

  • Date.prototype.getTimezoneOffset()

  • Date.prototype.getUTCDate()

  • Date.prototype.getUTCDay()

  • Date.prototype.getUTCFullYear()

  • Date.prototype.getUTCHours()

  • Date.prototype.getUTCMilliseconds()

  • Date.prototype.getUTCMinutes()

  • Date.prototype.getUTCMonth()

  • Date.prototype.getUTCSeconds()

  • Date.prototype.setDate()

  • Date.prototype.setFullYear()

  • Date.prototype.setHours()

  • Date.prototype.setMilliseconds()

  • Date.prototype.setMinutes()

  • Date.prototype.setMonth()

  • Date.prototype.setSeconds()

  • Date.prototype.setTime()

  • Date.prototype.setUTCDate()

  • Date.prototype.setUTCFullYear()

  • Date.prototype.setUTCHours()

  • Date.prototype.setUTCMilliseconds()

  • Date.prototype.setUTCMinutes()

  • Date.prototype.setUTCMonth()

  • Date.prototype.setUTCSeconds()

  • Date.prototype.toDateString()

  • Date.prototype.toISOString()

  • Date.prototype.toJSON()

  • Date.prototype.toLocaleDateString()

  • Date.prototype.toLocaleString()

  • Date.prototype.toLocaleTimeString()

  • Date.prototype.toString()

  • Date.prototype.toTimeString()

  • Date.prototype.toUTCString()

  • Date.prototype.valueOf()

• Error

  • Error.prototype.message

  • Error.prototype.name

  • Error.prototype.toString()

• EvalError

• Float32Array

• Float64Array

• Function

  • Function.length

  • Function.name

  • Function.prototype.apply()

  • Function.prototype.bind()

  • Function.prototype.call()

  • Function.prototype.toString()

• Generator

  • Generator.prototype.next()

  • Generator.prototype.return()

  • Generator.prototype.throw()

• Int16Array

• Int32Array

• Int8Array

• Intl

  • Intl.getCanonicalLocales()

• Intl.Collator

  • Intl.Collator.prototype.compare

  • Intl.Collator.prototype.resolvedOptions()

  • Intl.Collator.supportedLocalesOf()

• Intl.DateTimeFormat

  • Intl.DateTimeFormat.prototype.format

  • Intl.DateTimeFormat.prototype.formatToParts()

  • Intl.DateTimeFormat.prototype.resolvedOptions()

  • Intl.DateTimeFormat.supportedLocalesOf()

• Intl.NumberFormat

  • Intl.NumberFormat.prototype.format

  • Intl.NumberFormat.prototype.formatToParts()

  • Intl.NumberFormat.prototype.resolvedOptions()

  • Intl.NumberFormat.supportedLocalesOf()

• Intl.PluralRules

  • Intl.PluralRules.prototype.resolvedOptions()

  • Intl.PluralRules.select()

  • Intl.PluralRules.supportedLocalesOf()

• JSON

  • JSON.parse()

  • JSON.stringify()

• Map

  • Map.prototype.size

  • Map.prototype.clear()

  • Map.prototype.delete()

  • Map.prototype.entries()

  • Map.prototype.forEach()

  • Map.prototype.get()

  • Map.prototype.has()

  • Map.prototype.keys()

  • Map.prototype.set()

  • Map.prototype.values()

• Math

  • Math.abs()

  • Math.acos()

  • Math.acosh()

  • Math.asin()

  • Math.asinh()

  • Math.atan()

  • Math.atan2()

  • Math.atanh()

  • Math.cbrt()

  • Math.ceil()

  • Math.clz32()

  • Math.cos()

  • Math.cosh()

  • Math.exp()

  • Math.expm1()

  • Math.floor()

  • Math.fround()

  • Math.hypot()

  • Math.imul()

  • Math.log()

  • Math.log10()

  • Math.log1p()

  • Math.log2()

  • Math.max()

  • Math.min()

  • Math.pow()

  • Math.random()

  • Math.round()

  • Math.sign()

  • Math.sin()

  • Math.sinh()

  • Math.sqrt()

  • Math.tan()

  • Math.tanh()

  • Math.trunc()

• Number

  • Number.isFinite()

  • Number.isInteger()

  • Number.isNaN()

  • Number.isSafeInteger()

  • Number.parseFloat()

  • Number.parseInt()

  • Number.prototype.toExponential()

  • Number.prototype.toFixed()

  • Number.prototype.toLocaleString()

  • Number.prototype.toPrecision()

  • Number.prototype.toString()

  • Number.prototype.valueOf()

• Object

  • Object.prototype.constructor

  • Object.assign()

  • Object.create()

  • Object.defineProperties()

  • Object.defineProperty()

  • Object.entries()

  • Object.freeze()

  • Object.getOwnPropertyDescriptor()

  • Object.getOwnPropertyDescriptors()

  • Object.getOwnPropertyNames()

  • Object.getOwnPropertySymbols()

  • Object.getPrototypeOf()

  • Object.is()

  • Object.isExtensible()

  • Object.isFrozen()

  • Object.isSealed()

  • Object.keys()

  • Object.preventExtensions()

  • Object.prototype.hasOwnProperty()

  • Object.prototype.isPrototypeOf() (@belfz)

  • Object.prototype.propertyIsEnumerable() (@belfz )

  • Object.prototype.toLocaleString()

  • Object.prototype.toString() (@jonathan-s)

  • Object.prototype.valueOf()

  • Object.seal()

  • Object.setPrototypeOf()

  • Object.values()

• Promise

  • Promise.all()

  • Promise.prototype.catch()

  • Promise.prototype.finally()

  • Promise.prototype.then()

  • Promise.race()

  • Promise.reject()

  • Promise.resolve()

• Proxy

• RangeError

• ReferenceError

• Reflect

  • Reflect.apply()

  • Reflect.construct()

  • Reflect.defineProperty()

  • Reflect.deleteProperty()

  • Reflect.get()

  • Reflect.getOwnPropertyDescriptor()

  • Reflect.getPrototypeOf()

  • Reflect.has()

  • Reflect.isExtensible()

  • Reflect.ownKeys()

  • Reflect.preventExtensions()

  • Reflect.set()

  • Reflect.setPrototypeOf()

• RegExp

  • RegExp.$1-$9

  • RegExp.input ($_)

  • RegExp.lastMatch ($&)

  • RegExp.lastParen ($+)

  • RegExp.leftContext ($)`

  • RegExp.prototype.flags

  • RegExp.prototype.global

  • RegExp.prototype.ignoreCase

  • RegExp.prototype.multiline

  • RegExp.prototype.source

  • RegExp.prototype.sticky

  • RegExp.prototype.unicode

  • RegExp.rightContext ($')

  • regexp.lastIndex

  • RegExp.prototype.exec()

  • RegExp.prototype.test()

  • RegExp.prototype.toString()

• Set

  • Set.prototype.size

  • Set.prototype.add()

  • Set.prototype.clear()

  • Set.prototype.delete()

  • Set.prototype.entries()

  • Set.prototype.forEach()

  • Set.prototype.has()

  • Set.prototype.values()

• String

  • string.length

  • String.fromCharCode()

  • String.fromCodePoint()

  • String.prototype.charAt()

  • String.prototype.charCodeAt()

  • String.prototype.codePointAt()

  • String.prototype.concat()

  • String.prototype.endsWith()

  • String.prototype.includes()

  • String.prototype.indexOf()

  • String.prototype.lastIndexOf()

  • String.prototype.localeCompare()

  • String.prototype.match()

  • String.prototype.normalize()

  • String.prototype.padEnd()

  • String.prototype.padStart()

  • String.prototype.repeat()

  • String.prototype.replace()

  • String.prototype.search()

  • String.prototype.slice()

  • String.prototype.split()

  • String.prototype.startsWith()

  • String.prototype.substr()

  • String.prototype.substring()

  • String.prototype.toLocaleLowerCase()

  • String.prototype.toLocaleUpperCase()

  • String.prototype.toLowerCase()

  • String.prototype.toString()

  • String.prototype.toUpperCase()

  • String.prototype.trim()

  • String.prototype.trimEnd()

  • String.prototype.trimStart()

  • String.prototype.valueOf()

  • String.raw()

• Symbol

  • Symbol.hasInstance

  • Symbol.isConcatSpreadable

  • Symbol.iterator

  • Symbol.match

  • Symbol.replace

  • Symbol.search

  • Symbol.species

  • Symbol.split

  • Symbol.toPrimitive

  • Symbol.toStringTag

  • Symbol.unscopables

  • Symbol.for()

  • Symbol.keyFor()

  • Symbol.prototype.toString()

  • Symbol.prototype.valueOf()

• SyntaxError

• TypeError

• URIError

• Uint16Array

• Uint32Array

• Uint8Array

• Uint8ClampedArray

• WeakMap

  • WeakMap.prototype.delete()

  • WeakMap.prototype.get()

  • WeakMap.prototype.has()

  • WeakMap.prototype.set()

• WeakSet

  • WeakSet.prototype.add()

  • WeakSet.prototype.delete()

  • WeakSet.prototype.has()

• WebAssembly

  • WebAssembly.compile()

  • WebAssembly.instantiate()

  • WebAssembly.instantiateStreaming()

  • WebAssembly.validate()

• WebAssembly.Module

  • WebAssembly.Module.customSections()

  • WebAssembly.Module.exports()

  • WebAssembly.Module.imports()

• WebAssembly.Instance

  • WebAssembly.Instance.prototype.exports

• WebAssembly.Memory

  • WebAssembly.Memory.prototype.buffer

  • WebAssembly.Memory.prototype.grow

• WebAssembly.Table

  • WebAssembly.Table.prototype.length

  • WebAssembly.Table.prototype.get

  • WebAssembly.Table.prototype.grow

  • WebAssembly.Table.prototype.set

• WebAssembly.CompileError

• WebAssembly.LinkError

• WebAssembly.RuntimeError

• decodeURI()

• decodeURIComponent()

• encodeURI()

• encodeURIComponent()

• escape()

• eval()

• isFinite()

• isNaN()

• null

• parseFloat()

• parseInt()

• undefined

• unescape()

[coreh]

Would it make sense to reference (or perhaps even automatically convert?) the TypeScript definitions for these? Additional definitions are separated per ES version and available on this directory.

[fitzgen]

@coreh we are building a TypeScript frontend to wasm-bindgen (cc @spastorino) but it has a bit of a ways to go before we can rely on it. Additionally, .d.ts files don't give us information about whether a method can throw or not, so we would have to be conservative and assume that they always do, which isn't great to have at the most foundational layer of bindings.

For Web APIs, we intend to use our work-in-progress WebIDL frontend to generate a sys crate for the whole Web platform. WebIDL does give us more info, and crucially whether a method throws or not.

[sepiropht]

I would like to help! I know some Javascript and i' m currently learning rust. But i want to understand, maybe my question is silly. What is the purpose of all this bindings ?

[wismer]

How would multiple, optional arguments be handled for something like Array.prototype.concat? And on the subject of Array, would the type for this be Array<JsValue> ?

[fitzgen]

@sepiropht the purpose is so that we don't duplicate bindings across the ecosystem (or even within a single crate dependency graph) and people can be productive more quickly.

[fitzgen]

@wismer we don't have great support for optional arguments at the moment, so for now it is best to do one of:

• write bindings for a different function/object
• ignore the optional bindings
• always require the optional bindings

different choices may make sense for different methods.

[sepiropht]

Thanks @fitzgen and @fitzgen for the quick response. But this is still too advanced for me. Maybe i should start first by reading how wasm-bingen works.

[fitzgen]

@wismer

And on the subject of Array, would the type for this be Array ?

wasm-bindgen doesn't support generics right now (supporting generics across an ABI boundary without a JIT compiler to dynamically compile monomorphizations of generic instantiations is hard) so we would only support JsValue. It would be possible to build newtypes with phantoms on top of that that only let Rust code put in instances of the expected type, and then there would have to also be dynamic checks for the JS side of things somehow.

[wismer]

@fitzgen ok thanks - I'm eager to get started but I've run into a hiccup with the tests and it looks like it's a propagating JS error regarding WebAssembly is not defined - I've tried npm install and the link to the contributing guidelines is broken https://rustwasm.github.io/wasm-bindgen/contributing.html, so I'm not sure what build step I may be missing.

[fitzgen]

@wismer yeah, I'm trying to fix the gh-pages deploy on travis ci right now >.<

Make sure you've got node 10 installed (there are tests that depend on BigInt, which is >= 10; WebAssembly is >= 8).