JSArray<T extends JSAny?>#

Annotations: @JS('Array')

A JavaScript Array.

Because JSArray is an extension type, T is only a static guarantee and the array does not necessarily only contain T elements. For example:

@JS()
external JSArray<JSNumber> get array;

array is not actually checked to ensure it contains instances of JSNumber when called.

T may introduce additional checking elsewhere, however. When accessing elements of JSArray with type T, there is a check to ensure the element is a T to ensure soundness. Similarly, when converting to a <code>List<T></code>, casts may be introduced to ensure that it is indeed a <code>List<T></code>.

Constructors#

JSArray()#

Creates an empty JavaScript Array.

Equivalent to new Array() and more efficient than [].jsify().

external JSArray();

JSArray.withLength()#

Creates a JavaScript Array of size length with no elements.

external JSArray.withLength(int length);

Properties#

hashCode no setter inherited#

The hash code for this object.

A hash code is a single integer which represents the state of the object that affects operator == comparisons.

All objects have hash codes. The default hash code implemented by Object represents only the identity of the object, the same way as the default operator == implementation only considers objects equal if they are identical (see identityHashCode).

If operator == is overridden to use the object state instead, the hash code must also be changed to represent that state, otherwise the object cannot be used in hash based data structures like the default Set and Map implementations.

Hash codes must be the same for objects that are equal to each other according to operator ==. The hash code of an object should only change if the object changes in a way that affects equality. There are no further requirements for the hash codes. They need not be consistent between executions of the same program and there are no distribution guarantees.

Objects that are not equal are allowed to have the same hash code. It is even technically allowed that all instances have the same hash code, but if clashes happen too often, it may reduce the efficiency of hash-based data structures like HashSet or HashMap.

If a subclass overrides hashCode, it should override the operator == operator as well to maintain consistency.

Inherited from Object.

external int get hashCode;

isDefinedAndNotNull extension no setter#

Available on JSAny, provided by the NullableUndefineableJSAnyExtension extension

bool get isDefinedAndNotNull => !isUndefinedOrNull;

isNull extension no setter#

Whether this value corresponds to JavaScript null.

Available on JSAny, provided by the NullableUndefineableJSAnyExtension extension

external bool get isNull;

isTruthy extension no setter#

The result of <code>!!this</code> in JavaScript.

Available on JSAny, provided by the JSAnyOperatorExtension extension

external JSBoolean get isTruthy;

isUndefined extension no setter#

Whether this value corresponds to JavaScript undefined.

Available on JSAny, provided by the NullableUndefineableJSAnyExtension extension

external bool get isUndefined;

isUndefinedOrNull extension no setter#

Available on JSAny, provided by the NullableUndefineableJSAnyExtension extension

bool get isUndefinedOrNull => this == null;

length read / write#

getter:

The length in elements of this Array.

setter:

Sets the length in elements of this Array.

Setting it smaller than the current length truncates this Array, and setting it larger adds empty slots, which requires T to be nullable.

@Since('3.6')
external int get length;

@Since('3.6')
external set length(int newLength);

not extension no setter#

The result of <code>!this</code> in JavaScript.

Available on JSAny, provided by the JSAnyOperatorExtension extension

external JSBoolean get not;

runtimeType no setter inherited#

A representation of the runtime type of the object.

Inherited from Object.

external Type get runtimeType;

toDart extension no setter#

Converts this JSArray to a List by either casting or wrapping it.

When compiling to JavaScript, core Lists are Arrays and therefore, if the JSArray was already a <code>List<T></code> converted via ListToJSArray.toJS, this getter simply casts the Array. Otherwise, it wraps the Array with a List that casts the elements to T to ensure soundness.

When compiling to Wasm, the JSArray is wrapped with a List implementation and the wrapper is returned.

Modifications to this JSArray will affect the returned List and vice versa.

Available on JSArray<T extends JSAny?>, provided by the JSArrayToList<T extends JSAny?> extension

external List<T> get toDart;

Methods#

add()#

Adds value to the end of this Array, extending the length by one.

// This maps to `List.add` to avoid accidental usage of
// `JSAnyOperatorExtension.add` when migrating `List`s to `JSArray`s. See
// https://github.com/dart-lang/sdk/issues/59830.
@Since('3.10')
@JS('push')
external void add(T value);

add() extension#

The result of <code>this + any</code> in JavaScript.

Available on JSAny, provided by the JSAnyOperatorExtension extension

external JSAny add(JSAny? any);

and() extension#

The result of <code>this && any</code> in JavaScript.

Available on JSAny, provided by the JSAnyOperatorExtension extension

external JSAny? and(JSAny? any);

callMethod() extension#

Calls method on this JSObject with up to four arguments.

Returns the result of calling method, which must be an R.

This helper doesn't allow passing nulls, as it determines whether an argument is passed based on whether it was null or not. Prefer callMethodVarArgs if you need to pass nulls.

Available on JSObject, provided by the JSObjectUnsafeUtilExtension extension

R callMethod<R extends JSAny?>(
  JSAny method, [
  JSAny? arg1,
  JSAny? arg2,
  JSAny? arg3,
  JSAny? arg4,
]) => _callMethod(method, arg1, arg2, arg3, arg4) as R;

callMethodVarArgs() extension#

Calls method on this JSObject with a variable number of arguments.

Returns the result of calling method, which must be an R.

Available on JSObject, provided by the JSObjectUnsafeUtilExtension extension

R callMethodVarArgs<R extends JSAny?>(
  JSAny method, [
  List<JSAny?>? arguments,
]) => _callMethodVarArgs(method, arguments) as R;

dartify() extension#

Converts a JavaScript JSON-like value to the Dart equivalent if possible.

Effectively the inverse of NullableObjectUtilExtension.jsify, dartify takes a JavaScript JSON-like value and recursively converts it to a Dart object, doing the following:

• If the value is a string, number, boolean, null, undefined, DataView or a typed array, does the equivalent toDart operation if it exists and returns the result.
• If the value is a simple JS object (the protoype is either null or JS Object), creates and returns a [Map]<Object?, Object?> whose keys are the recursively converted keys obtained from Object.keys and its values are the associated values of the keys in the JS object.
• If the value is a JS Array, each item in it is recursively converted and added to a new [List]<Object?>, which is then returned.
• Otherwise, the conversion is undefined.

If the value contains a cycle, the behavior is undefined.

Available on JSAny, provided by the JSAnyUtilityExtension extension

// TODO(srujzs): We likely need stronger tests for this method to ensure
// consistency. We should also limit the accepted types in this API to avoid
// confusion. Once the conversion for unrelated types is consistent across all
// backends, we can update the documentation to say that the value is
// internalized instead of the conversion being undefined.
external Object? dartify();

delete() extension#

Deletes the property with key property from this JSObject.

Uses JavaScript's delete to delete the property.

Available on JSObject, provided by the JSObjectUnsafeUtilExtension extension

external JSBoolean delete(JSAny property);

divide() extension#

The result of <code>this / any</code> in JavaScript.

Available on JSAny, provided by the JSAnyOperatorExtension extension

external JSAny divide(JSAny? any);

equals() extension#

The result of <code>this == any</code> in JavaScript.

Available on JSAny, provided by the JSAnyOperatorExtension extension

external JSBoolean equals(JSAny? any);

exponentiate() extension#

The result of <code>this ** any</code> in JavaScript.

Available on JSAny, provided by the JSAnyOperatorExtension extension

external JSAny exponentiate(JSAny? any);

getProperty() extension#

The value of the property key property of this JSObject.

Available on JSObject, provided by the JSObjectUnsafeUtilExtension extension

external R getProperty<R extends JSAny?>(JSAny property);

greaterThan() extension#

The result of <code>this > any</code> in JavaScript.

Available on JSAny, provided by the JSAnyOperatorExtension extension

external JSBoolean greaterThan(JSAny? any);

greaterThanOrEqualTo() extension#

The result of <code>this >= any</code> in JavaScript.

Available on JSAny, provided by the JSAnyOperatorExtension extension

external JSBoolean greaterThanOrEqualTo(JSAny? any);

has() extension#

Shorthand helper for hasProperty to check whether this JSObject contains the property key property, but takes and returns a Dart value.

Available on JSObject, provided by the JSObjectUnsafeUtilExtension extension

bool has(String property) => hasProperty(property.toJS).toDart;

hasProperty() extension#

Whether or not this JSObject contains the property key property.

Uses JavaScript's in to check.

Available on JSObject, provided by the JSObjectUnsafeUtilExtension extension

external JSBoolean hasProperty(JSAny property);

instanceof() extension#

Whether this <code>JSAny?</code> is an instanceof constructor.

Available on JSAny, provided by the JSAnyUtilityExtension extension

external bool instanceof(JSFunction constructor);

instanceOfString() extension#

Whether this <code>JSAny?</code> is an instanceof the constructor that is defined by constructorName, which is looked up in the globalContext.

If constructorName contains '.'s, the name is split into several parts in order to get the constructor. For example, library1.JSClass would involve fetching library1 off of the globalContext, and then fetching JSClass off of library1 to get the constructor.

If constructorName is empty or any of the parts or the constructor don't exist, returns false.

Available on JSAny, provided by the JSAnyUtilityExtension extension

bool instanceOfString(String constructorName) {
  if (constructorName.isEmpty) return false;
  final parts = constructorName.split('.');
  JSObject? constructor = globalContext;
  for (final part in parts) {
    constructor = constructor?[part] as JSObject?;
    if (constructor == null) return false;
  }
  return instanceof(constructor as JSFunction);
}

isA() extension#

Whether this <code>JSAny?</code> is an instance of the JavaScript type that is declared by T.

Since the type-check this function emits is determined at compile-time, T needs to be an interop extension type that can also be determined at compile-time. In particular, isA can't be provided a generic type variable as a type argument.

This method uses a combination of null, typeof, and instanceof checks in order to do this check. Use this instead of is checks.

If T is a primitive JS type like JSString, this uses a typeof check that corresponds to that primitive type like typeofEquals('string').

If T is a non-primitive JS type like JSArray or an interop extension type on one, this uses an instanceof check using the name or the <code>@JS</code> rename of the given type like instanceOfString('Array'). Note that if you rename the library using the <code>@JS</code> annotation, this uses the rename in the instanceof check like instanceOfString('library1.JSClass').

To determine the JavaScript constructor to use as the second operand in the instanceof check, this function uses the JavaScript name associated with the extension type, which is either the argument given to the <code>@JS</code> annotation or the Dart declaration name. So, if you had an interop extension type JSClass that wraps JSArray without a rename, this does an instanceOfString('JSClass') check and not an instanceOfString('Array') check.

There are a few values for T that are exceptions to this rule:

• JSTypedArray: As TypedArray does not exist as a class in JavaScript, this does some prototype checking to make isA<JSTypedArray> do the right thing.
• JSBoxedDartObject: isA<JSBoxedDartObject> will check if the value is a result of a previous ObjectToJSBoxedDartObject.toJSBox call.
• JSAny: If you do an isA<JSAny> check, it will only check for null.
• User interop types whose representation types are JS primitive types: This will result in an error to avoid confusion on whether the user interop type is used in the type-check. Use the primitive JS type as the value for T instead.
• User interop types that have an object literal constructor: This will result in an error as you likely want to use JSObject instead.

Available on JSAny, provided by the JSAnyUtilityExtension extension

@Since('3.4')
external bool isA<T extends JSAny?>();

lessThan() extension#

The result of <code>this < any</code> in JavaScript.

Available on JSAny, provided by the JSAnyOperatorExtension extension

external JSBoolean lessThan(JSAny? any);

lessThanOrEqualTo() extension#

The result of <code>this <= any</code> in JavaScript.

Available on JSAny, provided by the JSAnyOperatorExtension extension

external JSBoolean lessThanOrEqualTo(JSAny? any);

modulo() extension#

The result of <code>this % any</code> in JavaScript.

Available on JSAny, provided by the JSAnyOperatorExtension extension

external JSAny modulo(JSAny? any);

multiply() extension#

The result of <code>this * any</code> in JavaScript.

Available on JSAny, provided by the JSAnyOperatorExtension extension

external JSAny multiply(JSAny? any);

noSuchMethod() inherited#

Invoked when a nonexistent method or property is accessed.

A dynamic member invocation can attempt to call a member which doesn't exist on the receiving object. Example:

dynamic object = 1;
object.add(42); // Statically allowed, run-time error

This invalid code will invoke the noSuchMethod method of the integer 1 with an Invocation representing the .add(42) call and arguments (which then throws).

Classes can override noSuchMethod to provide custom behavior for such invalid dynamic invocations.

A class with a non-default noSuchMethod invocation can also omit implementations for members of its interface. Example:

class MockList<T> implements List<T> {
  noSuchMethod(Invocation invocation) {
    log(invocation);
    super.noSuchMethod(invocation); // Will throw.
  }
}
void main() {
  MockList().add(42);
}

This code has no compile-time warnings or errors even though the MockList class has no concrete implementation of any of the List interface methods. Calls to List methods are forwarded to noSuchMethod, so this code will log an invocation similar to Invocation.method(#add, [42]) and then throw.

If a value is returned from noSuchMethod, it becomes the result of the original invocation. If the value is not of a type that can be returned by the original invocation, a type error occurs at the invocation.

The default behavior is to throw a NoSuchMethodError.

Inherited from Object.

@pragma("vm:entry-point")
@pragma("wasm:entry-point")
external dynamic noSuchMethod(Invocation invocation);

notEquals() extension#

The result of <code>this != any</code> in JavaScript.

Available on JSAny, provided by the JSAnyOperatorExtension extension

external JSBoolean notEquals(JSAny? any);

or() extension#

The result of <code>this || any</code> in JavaScript.

Available on JSAny, provided by the JSAnyOperatorExtension extension

external JSAny? or(JSAny? any);

setProperty() extension#

Write the value of property key property of this JSObject.

Available on JSObject, provided by the JSObjectUnsafeUtilExtension extension

external void setProperty(JSAny property, JSAny? value);

strictEquals() extension#

The result of <code>this === any</code> in JavaScript.

Available on JSAny, provided by the JSAnyOperatorExtension extension

external JSBoolean strictEquals(JSAny? any);

strictNotEquals() extension#

The result of <code>this !== any</code> in JavaScript.

Available on JSAny, provided by the JSAnyOperatorExtension extension

external JSBoolean strictNotEquals(JSAny? any);

subtract() extension#

The result of <code>this - any</code> in JavaScript.

Available on JSAny, provided by the JSAnyOperatorExtension extension

external JSAny subtract(JSAny? any);

toString() inherited#

A string representation of this object.

Some classes have a default textual representation, often paired with a static parse function (like int.parse). These classes will provide the textual representation as their string representation.

Other classes have no meaningful textual representation that a program will care about. Such classes will typically override toString to provide useful information when inspecting the object, mainly for debugging or logging.

Inherited from Object.

external String toString();

typeofEquals() extension#

Whether the result of typeof on this <code>JSAny?</code> is typeString.

Available on JSAny, provided by the JSAnyUtilityExtension extension

external bool typeofEquals(String typeString);

unsignedRightShift() extension#

The result of <code>this >>> any</code> in JavaScript.

Available on JSAny, provided by the JSAnyOperatorExtension extension

// TODO(srujzs): This should return `num` or `double` instead.
external JSNumber unsignedRightShift(JSAny? any);

Operators#

operator ==() inherited#

The equality operator.

The default behavior for all Objects is to return true if and only if this object and other are the same object.

Override this method to specify a different equality relation on a class. The overriding method must still be an equivalence relation. That is, it must be:

• Total: It must return a boolean for all arguments. It should never throw.

• Reflexive: For all objects o, o == o must be true.

• Symmetric: For all objects o1 and o2, o1 == o2 and o2 == o1 must either both be true, or both be false.

• Transitive: For all objects o1, o2, and o3, if o1 == o2 and o2 == o3 are true, then o1 == o3 must be true.

The method should also be consistent over time, so whether two objects are equal should only change if at least one of the objects was modified.

If a subclass overrides the equality operator, it should override the hashCode method as well to maintain consistency.

Inherited from Object.

external bool operator ==(Object other);

operator []()#

The value at position in this Array.

@Since('3.6')
external T operator [](int position);

operator []() extension#

Shorthand helper for getProperty to get the value of the property key property of this JSObject, but takes a Dart value.

Available on JSObject, provided by the JSObjectUnsafeUtilExtension extension

JSAny? operator [](String property) => getProperty(property.toJS);

operator []=()#

Sets the value at position in this Array.

@Since('3.6')
external void operator []=(int position, T value);

operator []=() extension#

Shorthand helper for setProperty to write the value of the property key property of this JSObject, but takes a Dart value.

Available on JSObject, provided by the JSObjectUnsafeUtilExtension extension

void operator []=(String property, JSAny? value) =>
    setProperty(property.toJS, value);

Static Methods#

from()#

Creates a new, shallow-copied JavaScript Array instance from a JavaScript iterable or array-like object.

@Since('3.6')
external static JSArray<T> from<T extends JSAny>(JSObject arrayLike);