package js
Types, methods and values for interoperability with JavaScript libraries.
This package is only relevant to the Scala.js compiler, and should not be referenced by any project compiled to the JVM.
Guide
General documentation on Scala.js is available at http://www.scala-js.org/doc/.
Overview
The trait js.Any is the root of the hierarchy of JavaScript types. This package defines important subtypes of js.Any that are defined in the standard library of ECMAScript 5.1 (or ES 6, with a label in the documentation), such as js.Object, js.Array and js.RegExp.
Implicit conversions to and from standard Scala types to their equivalent in JavaScript are provided. For example, from Scala functions to JavaScript functions and back.
The most important subtypes of js.Any declared in this package are:
- js.Object, the superclass of most (all) JavaScript classes
- js.Array
- js.Function (and subtraits with specific number of parameters)
- js.ThisFunction and its subtraits for functions that
take the JavaScript
this
as an explicit parameter - js.Dictionary, a Map-like view of the properties of a JS object
The trait js.Dynamic is a special subtrait of js.Any. It can represent any JavaScript value in a dynamically-typed way. It is possible to call any method and read and write any field of a value of type js.Dynamic.
There are no explicit definitions for JavaScript primitive types, as one could expect, because the corresponding Scala types stand in their stead:
- Boolean is the type of primitive JavaScript booleans
- Double is the type of primitive JavaScript numbers
- String is the type of primitive JavaScript strings (or
null
) - Unit is the type of the JavaScript undefined value
Null
is the type of the JavaScript null value
js.UndefOr gives a scala.Option-like interface where the
JavaScript value undefined
takes the role of None
.
A | B is an unboxed pseudo-union type, suitable to type values that admit several unrelated types in facade types.
- Alphabetic
- By Inheritance
- js
- AnyRef
- Any
- Hide All
- Show All
- Public
- All
Type Members
-
trait
Any extends AnyRef
Root of the hierarchy of JavaScript types.
Root of the hierarchy of JavaScript types.
Subtypes of js.Any are JavaScript types, which have different semantics and guarantees than Scala types (subtypes of AnyRef and AnyVal). Operations on JavaScript types behave as the corresponding operations in the JavaScript language.
By default, JavaScript types are native: they are facade types to APIs implemented in JavaScript code. Their implementation is irrelevant and never emitted. As such, all members must be defined with their right-hand-side being js.native. For forward source compatibility with the next major version, the class/trait/object itself should be annotated with @js.native. This becomes mandatory with the compiler option
-P:scalajs:sjsDefinedByDefault
.In most cases, you should not directly extend this trait, but rather extend js.Object.
To implement a JavaScript type in Scala.js (therefore non-native), you must add
-P:scalajs:sjsDefinedByDefault
to your scalac options. Scala.js-defined JS types cannot directly extend native JS traits; and Scala.js-defined JS traits cannot declare concrete term members.It is not possible to define traits or classes that inherit both from this trait and a strict subtype of AnyRef. In fact, you should think of js.Any as a third direct subclass of scala.Any, besides scala.AnyRef and scala.AnyVal.
See the JavaScript interoperability guide of Scala.js for more details.
- Annotations
- @ScalaJSDefined() @RawJSType()
-
class
Array[A] extends Object with Iterable[A]
Arrays are list-like objects whose prototype has methods to perform traversal and mutation operations.
Arrays are list-like objects whose prototype has methods to perform traversal and mutation operations. Neither the length of a JavaScript array nor the types of its elements are fixed. Since an array's size length grow or shrink at any time, JavaScript arrays are not guaranteed to be dense. In general, these are convenient characteristics; but if these features are not desirable for your particular use, you might consider using typed arrays.
MDN
To construct a new array with uninitialized elements, use the constructor of this class. To construct a new array with specified elements, as if you used the array literal syntax in JavaScript, use the Array.apply method instead.
- A
Type of the elements of the array
-
final
class
ArrayOps[A] extends ArrayLike[A, Array[A]] with Builder[A, Array[A]]
Equivalent of scm.ArrayOps for js.Array
Equivalent of scm.ArrayOps for js.Array
- Annotations
- @inline()
-
final
class
ConstructorTag[T <: Any] extends AnyVal
Stores the JS constructor function of a JS class.
Stores the JS constructor function of a JS class.
A
ConstructorTag[T]
holds the constructor function of a JS class, as retrieved byjs.constructorOf[T]
. Similarly to ClassTags,ConstructorTag
s can be implicitly materialized whenT
is statically known to be a JS class, i.e., a valid type argument tojs.constructorOf
. -
class
Date extends Object
Creates a JavaScript Date instance that represents a single moment in time.
-
sealed
trait
Dictionary[A] extends Any
Dictionary "view" of a JavaScript value.
Dictionary "view" of a JavaScript value.
Using objects as dictionaries (maps from strings to values) through their properties is a common idiom in JavaScript. This trait lets you treat an object as such a dictionary, with the familiar API of a Map.
To use it, cast your object, say
x
, into a Dictionary usingval xDict = x.asInstanceOf[js.Dictionary[Int]]
then use it as
xDict("prop") = 5 println(xDict.get("prop")) // displays Some(5) xDict -= "prop" // removes the property "prop" println(xDict.get("prop")) // displays None
To enumerate all the keys of a dictionary, use collection methods or for comprehensions. For example:
for ((prop, value) <- xDict) { println(prop + " -> " + value) }
Note that this does not enumerate properties in the prototype chain of
xDict
.This trait extends js.Any directly, because it is not safe to call methods of js.Object on it, given that the name of these methods could be used as keys in the dictionary.
-
sealed
trait
Dynamic extends Any with scala.Dynamic
Dynamically typed JavaScript value.
- class Error extends Object
-
class
EvalError extends Error
An instance representing an error that occurs regarding the global function eval()
-
class
Function extends Object
The Function constructor creates a new Function object.
The Function constructor creates a new Function object. In JavaScript every function is actually a Function object.
Function objects created with the Function constructor are parsed when the function is created. This is less efficient than declaring a function and calling it within your code, because functions declared with the function statement are parsed with the rest of the code.
All arguments passed to the function are treated as the names of the identifiers of the parameters in the function to be created, in the order in which they are passed.
Note: Functions created with the Function constructor do not create closures to their creation contexts; they always are created in the global scope. When running them, they will only be able to access their own local variables and global ones, not the ones from the scope in which the Function constructor was called. This is different from using eval with code for a function expression.
Invoking the Function constructor as a function (without using the new operator) has the same effect as invoking it as a constructor.
MDN
- trait Function0[+R] extends Function
- trait Function1[-T1, +R] extends Function
- trait Function2[-T1, -T2, +R] extends Function
-
trait
Iterable[+A] extends Object
ECMAScript 6 JavaScript Iterable.
ECMAScript 6 JavaScript Iterable.
- Annotations
- @ScalaJSDefined() @RawJSType()
-
final
class
IterableOps[+A] extends collection.Iterable[A]
Adapts a JavaScript Iterable to a Scala Iterable
Adapts a JavaScript Iterable to a Scala Iterable
- Annotations
- @inline()
-
trait
Iterator[+A] extends Object
ECMAScript 6 JavaScript Iterator.
ECMAScript 6 JavaScript Iterator.
- Annotations
- @ScalaJSDefined() @RawJSType()
- sealed abstract class JSConvertersLowPrioImplicits extends AnyRef
-
trait
JSNumberOps extends Any
Operations on JavaScript numbers.
-
trait
JSStringOps extends Any
Operations on JavaScript strings.
- case class JavaScriptException(exception: scala.Any) extends RuntimeException with Product with Serializable
- trait LowPrioAnyImplicits extends LowestPrioAnyImplicits
- sealed trait LowestPrioAnyImplicits extends AnyRef
-
class
Object extends Any
Base class of all JavaScript objects.
-
class
Promise[+A] extends Object with Thenable[A]
ECMAScript 6 Promise of an asynchronous result.
ECMAScript 6 Promise of an asynchronous result.
Attention! The nature of this class, from the ECMAScript specification, makes it inherently un-typeable, because it is not type parametric.
The signatures of the constructor and the methods
then
andcatch
are only valid provided that the values ofA
andB
are not Thenables.We recommend to use Scala's
Future
s instead ofPromise
as much as possible. APromise
can be converted to aFuture
with.toFuture
and back with.toJSPromise
(provided by JSConverters).With
import scala.scalajs.js.Thenable.Implicits._
you can implicitly convert a
Promise
to aFuture
, and therefore you can directly use the methods ofFuture
onPromise
s. - trait PropertyDescriptor extends Object
-
class
RangeError extends Error
An instance representing an error that occurs when a numeric variable or parameter is outside of its valid range.
An instance representing an error that occurs when a numeric variable or parameter is outside of its valid range.
A RangeError is thrown when trying to pass a number as an argument to a function that does not allow a range that includes that number. This can be encountered when to create an array of an illegal length with the Array constructor, or when passing bad values to the numeric methods toExponential, toFixed, or toPrecision.
MDN
-
class
ReferenceError extends Error
Represents an error when a non-existent variable is referenced.
-
class
RegExp extends Object
The RegExp constructor creates a regular expression object for matching text with a pattern.
-
sealed
trait
Symbol extends Any
ECMAScript 6 JavaScript Symbol.
-
class
SyntaxError extends Error
Represents an error when trying to interpret syntactically invalid code.
-
trait
Thenable[+A] extends Object
A thing on which one can call the
then
method.A thing on which one can call the
then
method.Thenable
s are automatically transitively flattened by thethen
method ofThenable
s. In particular, this is true for Promises.Attention! The nature of this interface, from the ECMAScript specification, makes it inherently un-typeable, because it is not type parametric.
The signature of the
then
method is only valid provided that the values ofB
do not have athen
method.- Annotations
- @ScalaJSDefined() @RawJSType()
-
trait
ThisFunction extends Function
A JavaScript function where
this
is considered as a first parameter. - trait ThisFunction0[-T0, +R] extends Function with ThisFunction
- trait ThisFunction1[-T0, -T1, +R] extends Function with ThisFunction
- trait ThisFunction2[-T0, -T1, -T2, +R] extends Function with ThisFunction
-
sealed
trait
Tuple2[+T1, +T2] extends Object
A tuple "view" of 2 elements of a JavaScript Array.
A tuple "view" of 2 elements of a JavaScript Array. Combines
0: T0; 1: T1;
to
js.Tuple2[T0,T1]
Supports implicit conversion to scala.Tuple2. To use it, cast your array into a Tuple2 using
val array = js.Array[Any](42, "foobar") val tuple2 = array.asInstanceOf[js.Tuple2[Int, String]]
or convert a Scala tuple
val obj: js.Tuple2[Int, String] = (42, "foobar")
-
sealed
trait
Tuple3[+T1, +T2, +T3] extends Object
A tuple "view" of 3 elements of a JavaScript Array.
-
class
TypeError extends Error
Represents an error when a value is not of the expected type.
-
class
URIError extends Error
Represents an error when a malformed URI is encountered.
-
sealed
trait
UndefOr[+A] extends AnyRef
Value of type A or the JS undefined value.
Value of type A or the JS undefined value.
js.UndefOr[A]
is the type of a value that can be eitherundefined
or anA
. It provides an API similar to that of scala.Option through the UndefOrOps implicit class, whereundefined
take the role of None.By extension, this type is also suited to typing optional fields in native JS types, i.e., fields that may not exist on the object.
- Annotations
- @RawJSType()
- sealed abstract class UndefOrLowPrioImplicits extends AnyRef
- final class UndefOrOps[A] extends AnyVal
-
sealed
trait
UnicodeNormalizationForm extends Any
A Unicode Normalization Form.
-
final
class
Using[A] extends AnyVal
Helper for syntactic sugar of js.use.
Helper for syntactic sugar of js.use. Only use in
js.use(x).as[T]
-
final
class
WrappedArray[A] extends AbstractBuffer[A] with GenericTraversableTemplate[A, WrappedArray] with collection.mutable.IndexedSeq[A] with BufferLike[A, WrappedArray[A]] with ArrayLike[A, WrappedArray[A]] with Builder[A, WrappedArray[A]]
Equivalent of scm.WrappedArray for js.Array
Equivalent of scm.WrappedArray for js.Array
- Annotations
- @inline()
-
class
WrappedDictionary[A] extends AbstractMap[String, A] with Map[String, A] with MapLike[String, A, WrappedDictionary[A]]
Wrapper to use a js.Dictionary as a scala.mutable.Map
Wrapper to use a js.Dictionary as a scala.mutable.Map
- Annotations
- @inline()
-
class
native extends Annotation with StaticAnnotation
Marks the annotated class, trait or object as a native JS entity.
Marks the annotated class, trait or object as a native JS entity.
Native JS entities are not implemented in Scala.js. They are facade types for native JS libraries.
In Scala.js 0.6.x, all types extending js.Any are native by default (unless they are annotated with annotation.ScalaJSDefined), but this will not be the case in the next major version anymore.
Only types extending js.Any can be annotated with
@js.native
. The body of all concrete members in a native JS class, trait or object must be= js.native
. -
sealed
trait
|[A, B] extends AnyRef
Value of type A or B (union type).
Value of type A or B (union type).
Scala does not have union types, but they are important to many interoperability scenarios. This type provides a (partial) encoding of union types using implicit evidences.
- Annotations
- @RawJSType()
-
trait
GlobalScope extends Any
Marker trait for top-level objects representing the JS global scope.
Marker trait for top-level objects representing the JS global scope.
When calling method on a top-level object or package object that is a subtype of GlobalScope, the receiver is dropped, and the JavaScript global scope is used instead.
-
trait
JSApp extends AnyRef
Old-style base class for top-level, entry point main objects.
Old-style base class for top-level, entry point main objects.
JSApp provides two services to an
object Foo
that extends it. These two services are replaced by two different features, starting with Scala.js 0.6.18.Discoverability by sbt as main object
Since Scala.js 0.6.18, the sbt plugin can recognize "standard"
main
methods of the formdef main(args: Array[String]): Unit = ...
in objects, even if they do not extend
JSApp
. Use such a main method to replace JSApp in the context of discoverability by sbt.To enable it as main method, make sure you also set
scalaJSUseMainModuleInitializer := true
in your project settings.
Automatic export to JavaScript
Given
package bar object Foo extends js.JSApp { def main(): Unit = println("Hello world!") }
the object
Foo
and itsmain
method are automatically exported such that JavaScript code can callbar.Foo().main();
To achieve exactly the same behavior without JSApp, define
Foo
aspackage bar object Foo { @JSExportTopLevel("bar.Foo") protected def getInstance(): this.type = this @JSExport def main(): Unit = println("Hello world!") }
Alternatively, you can define it as
package bar object Foo { @JSExportTopLevel("bar.Foo.main") def main(): Unit = println("Hello world!") }
but in that case, the JavaScript code will have to be changed to
bar.Foo.main()
- Annotations
- @deprecated @JSExportDescendentObjects()
- Deprecated
(Since version 0.6.20) Consult the Scaladoc of js.JSApp for migration tips.
-
trait
JSArrayOps[A] extends Object
Discouraged native JavaScript Array methods.
Discouraged native JavaScript Array methods.
In general, you should prefer the Scala collection methods available implicitly through ArrayOps, because they are inlineable, and hence faster.
To enable the use of these functions on js.Arrays, import the implicit conversion JSArrayOps.jsArrayOps.
Value Members
-
def
constructorOf[T <: Any]: Dynamic
Returns the constructor function of a JavaScript class.
Returns the constructor function of a JavaScript class.
The specified type parameter
T
must be a class type (i.e., valid forclassOf[T]
) and represent a class extendingjs.Any
(not a trait nor an object). -
def
constructorTag[T <: Any](implicit tag: ConstructorTag[T]): ConstructorTag[T]
Makes explicit an implicitly available
ConstructorTag[T]
. -
def
eval(x: String): Any
Evaluates JavaScript code and returns the result.
Evaluates JavaScript code and returns the result.
- Annotations
- @inline()
-
def
isUndefined(v: scala.Any): Boolean
Tests whether the given value is undefined.
Tests whether the given value is undefined.
- Annotations
- @inline()
-
def
native: Nothing
Denotes a method body as native JavaScript.
Denotes a method body as native JavaScript. For use in facade types:
class MyJSClass extends js.Object { def myMethod(x: String): Int = js.native }
-
def
typeOf(x: Any): String
Returns the type of
x
as identified bytypeof x
in JavaScript. -
def
undefined: UndefOr[Nothing]
The undefined value.
The undefined value.
- Annotations
- @inline()
-
def
use[A](x: A): Using[A]
Allows to cast a value to a facade trait in a type-safe way.
Allows to cast a value to a facade trait in a type-safe way.
Use as follows:
js.use(x).as[MyFacade]
Note that the method calls are only syntactic sugar. There is no overhead at runtime for such an operation. Using
use(x).as[T]
is strictly equivalent tox.asInstanceOf[T]
if the compile time check does not fail.This method supports both Scala classes with exports and facade types which are structurally equivalent.
Examples
Given the following facade type:
trait MyFacade extends js.Object { def foo(x: Int): String = js.native val bar: Int = js.native }
We show a couple of examples:
class MyClass1 { @JSExport def foo(x: Int): String = x.toString @JSExport val bar: Int = 1 } val x1 = new MyClass1 js.use(x1).as[MyFacade] // OK
Note that JS conventions apply: The
val bar
can be implemented with adef
.class MyClass2 { @JSExport def foo(x: Int): String = x.toString @JSExport def bar: Int = 1 // def instead of val } val x2 = new MyClass2 js.use(x2).as[MyFacade] // OK
Missing methods or methods with wrong types will cause a compile-time failure.
class MyClass3 { @JSExport def foo(x: String): String = x.toString // wrong type signature // bar is missing } val x3 = new MyClass3 js.use(x2).as[MyFacade] // Fails: bar is missing and foo has wrong type
Methods must be exported, otherwise they are not taken into consideration.
class MyClass4 { def foo(x: Int): String = x.toString @JSExport def bar: Int = 1 // def instead of val } val x4 = new MyClass4 js.use(x4).as[MyFacade] // Fails, foo is missing
Other facade types can also be used
trait MyOtherFacade extends js.Object { def foo(x: Any): String = js.native val bar: Int = js.native def otherMethod(): Unit = js.native } val x5: MyOtherFacade = // ... js.use(x5).as[MyFacade] // OK
Restrictions
- Facade types may only be traits and not have any class ancestors
- Polymorphic methods are currently not supported
- Facade types defining an apply method cannot used (this is a JavaScript restriction).
-
object
Any extends LowPrioAnyImplicits
Provides implicit conversions from Scala values to JavaScript values.
-
object
Array extends Object
Factory for js.Array objects.
- object ConstructorTag
-
object
Date extends Object
Factory for js.Date objects.
-
object
Dictionary
Factory for Dictionary instances.
-
object
Dynamic
Factory for dynamically typed JavaScript values.
-
object
DynamicImplicits
Provides implicit conversions and operations to write in JavaScript style with js.Dynamic.
Provides implicit conversions and operations to write in JavaScript style with js.Dynamic.
Be **very** careful when importing members of this object. You may want to selectively import the implicits that you want to reduce the likelihood of making mistakes.
- object Error extends Object
- object EvalError extends Object
- object Function extends Object
- object Iterator
-
object
JSConverters extends JSConvertersLowPrioImplicits
A collection of decorators that allow converting Scala types to corresponding JS facade types
- object JSNumberOps
-
object
JSON extends Object
The JSON object contains methods for converting values to JavaScript Object Notation (JSON) and for converting JSON to values.
- object JSStringOps
-
object
Math extends Object
Math is a built-in object that has properties and methods for mathematical constants and functions.
-
object
Object extends Object
The top-level
Object
JavaScript object. - object Promise extends Object
- object RangeError extends Object
- object ReferenceError extends Object
- object RegExp extends Object
-
object
Symbol extends Object
ECMAScript 6 Factory for js.Symbols and well-known symbols.
- object SyntaxError extends Object
- object Thenable
- object ThisFunction
- object Tuple2
- object Tuple3
- object TypeError extends Object
- object URIError extends Object
-
object
URIUtils extends Object
Methods related to URIs, provided by ECMAScript 5.1.
Methods related to URIs, provided by ECMAScript 5.1.
- Annotations
- @native() @JSGlobalScope()
- object UndefOr extends UndefOrLowPrioImplicits
- object UndefOrOps
- object UnicodeNormalizationForm
-
object
WrappedArray extends SeqFactory[WrappedArray]
Factory for WrappedArray.
Factory for WrappedArray. Mainly provides the relevant CanBuildFromss and implicit conversions.
- object WrappedDictionary
- object defined
- object |
Deprecated Value Members
-
def
debugger(): Unit
Invokes any available debugging functionality.
Invokes any available debugging functionality. If no debugging functionality is available, this statement has no effect.
MDN
Browser support:
- Has no effect in Rhino nor, apparently, in Firefox
- In Chrome, it has no effect unless the developer tools are opened beforehand.
- Annotations
- @deprecated @inline()
- Deprecated
(Since version 0.6.17) Use scala.scalajs.js.sepcial.debugger instead
-
object
ArrayOps
- Annotations
- @deprecated
- Deprecated
(Since version 0.6.23) Kept only for binary compatibility
-
object
JSArrayOps
- Annotations
- @deprecated
- Deprecated
(Since version 0.6.25)