dart:js_interop library

A library for JS interop. Includes a JS type hierarchy to facilitate sound interop with JS. The JS type hierarchy is modeled after the actual type hierarchy in JS, and not the Dart type hierarchy.

Note: The JS types defined in this library only provide static guarantees. The runtime types differ based on the backend, so rely on static functionality like the conversion functions e.g. toJS and not runtime mechanisms like type checks and casts.

WARNING: This library is still a work in progress. As such, JS types, allowed syntax, semantics, and functionality may all change, so avoid using this library in production.

Classes

JS
The annotation for JS interop members.
JSExport
Annotation to mark Dart classes as exportable and allow instance members to be wrapped with an object literal.

Extensions

BoolToJSBoolean
ByteBufferToJSArrayBuffer
ByteDataToJSDataView
DoubleToJSNumber
double -> JSNumber.
Float32ListToJSFloat32Array
Float64ListToJSFloat64Array
FunctionToJSExportedDartFunction
FutureOfJSAnyToJSPromise
FutureOfVoidToJSPromise
Int16ListToJSInt16Array
Int32ListToJSInt32Array
Int8ListToJSInt8Array
JSAnyOperatorExtension
JSAnyUtilityExtension
Common utility functions that are useful for any JS value.
JSArrayBufferToByteBuffer
JSArrayBuffer <-> ByteBuffer
JSArrayToList
JSArray <-> List
JSBooleanToBool
JSBoolean <-> bool
JSBoxedDartObjectToObject
JSBoxedDartObject <-> Object
JSDataViewToByteData
JSDataView <-> ByteData
JSExportedDartFunctionToFunction
JSExportedDartFunction <-> Function
JSFloat32ArrayToFloat32List
JSFloat32Array <-> Float32List
JSFloat64ArrayToFloat64List
JSFloat64Array <-> Float64List
JSFunctionUtilExtension
Utility extensions for JSFunction.
JSInt16ArrayToInt16List
JSInt16Array <-> Int16List
JSInt32ArrayToInt32List
JSInt32Array <-> Int32List
JSInt8ArrayToInt8List
JSInt8Array <-> Int8List
JSNumberToNumber
JSNumber -> double or int.
JSPromiseToFuture
JSPromise -> Future.
JSStringToString
JSString <-> String
JSUint16ArrayToInt16List
JSUint16Array <-> Uint16List
JSUint32ArrayToUint32List
JSUint32Array <-> Uint32List
JSUint8ArrayToUint8List
JSUint8Array <-> Uint8List
JSUint8ClampedArrayToUint8ClampedList
JSUint8ClampedArray <-> Uint8ClampedList
ListToJSArray
NullableObjectUtilExtension
Utility extensions for Object?.
NullableUndefineableJSAnyExtension
JS undefined and JS null are internalized differently based on the backends. In the JS backends, Dart null can actually be JS undefined or JS null. In dart2wasm, that's not the case: there's only one Wasm value null can be. Therefore, when we get back JS null or JS undefined, we internalize both as Dart null in dart2wasm, and when we pass Dart null to an interop API, we pass JS null. In the JS backends, Dart null retains its original value when passed back to an interop API. Be wary of writing code where this distinction between null and undefined matters.
NumToJSExtension
num -> JSNumber.
ObjectToJSBoxedDartObject
StringToJSString
Uint16ListToJSInt16Array
Uint32ListToJSUint32Array
Uint8ClampedListToJSUint8ClampedArray
Uint8ListToJSUint8Array

Extension Types

JSAny
The JS types users should use to write their external APIs.
JSArray
The type of all JS arrays.
JSArrayBuffer
The type of JS' ArrayBuffer.
JSBigInt
The type of JS BigInts.
JSBoolean
The type of JS booleans.
JSBoxedDartObject
The type of the boxed Dart object that can be passed to JS safely. There is no interface specified of this boxed object, and you may get a new box each time you box the same Dart object.
JSDataView
The type of JS' DataView.
JSExportedDartFunction
The type of all Dart functions adapted to be callable from JS. We only allow a subset of Dart functions to be callable from JS.
JSFloat32Array
The type of JS' Float32Array.
JSFloat64Array
The type of JS' Float64Array.
JSFunction
The type of all JS functions.
JSInt16Array
The type of JS' Int16Array.
JSInt32Array
The type of JS' Int32Array.
JSInt8Array
The type of JS' Int8Array.
JSNumber
The type of JS numbers.
JSObject
The representation type of all JavaScript objects for extension types.
JSPromise
The type of JS promises and promise-like objects.
JSString
The type of JS strings.
JSSymbol
The type of JS Symbols.
JSTypedArray
The abstract supertype of all JS typed arrays.
JSUint16Array
The type of JS' Uint16Array.
JSUint32Array
The type of JS' Uint32Array.
JSUint8Array
The type of JS' Uint8Array.
JSUint8ClampedArray
The type of JS' Uint8ClampedArray.

Constants

anonymous → const _Anonymous
An annotation that indicates a JS annotated class is structural and does not have a known JavaScript prototype.
staticInterop → const _StaticInterop
staticInterop enables the JS annotated class to be treated as a "static" interop class.

Properties

globalContext → JSObject
A getter to retrieve the global context that is used in static interop lowering.
no setter

Functions

createJSInteropWrapper<T extends Object>(T dartObject) → JSObject
Given a Dart object that is marked "exportable", creates a JS object that wraps the given Dart object. Look at the @JSExport annotation to determine what constitutes "exportable" for a Dart class. The object literal will be a map of export names (which are either the written instance member names or their rename) to their respective Dart instance members.
importModule(String moduleName) → JSPromise<JSObject>
Call to dynamically import a JS module with the given moduleName using the JS import() syntax.

Typedefs

JSVoid = void
The type of JSUndefined when returned from functions. Unlike pure JS, no actual object will be returned.

Exceptions / Errors

NullRejectionException
Exception for when the promise is rejected with a null or undefined value.