JSSymbol

extension type JSSymbol(JSSymbolRepType) implements JSAny

Annotations: @JS('Symbol')

A JavaScript Symbol.

Constructors

JSSymbol()

JSSymbol([String? description])

Creates a new, unique JavaScript Symbol.

If description is provided, it's used for debugging but not to access the symbol itself.

Implementation

@Since('3.11')
JSSymbol([String? description])
  : _jsSymbol =
        (description == null
                ? _constructSymbol()
                : _constructSymbol(description))
            ._jsSymbol;

Properties

description no setter

String get description

A string containing the description of the symbol, as passed to JSSymbol.new.

Implementation

@Since('3.11')
external String get description;

hashCode no setter inherited

int get hashCode

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.

Implementation

external int get hashCode;

isDefinedAndNotNull extension no setter

bool get isDefinedAndNotNull

Available on JSAny, provided by the NullableUndefineableJSAnyExtension extension

Implementation

bool get isDefinedAndNotNull => !isUndefinedOrNull;

isNull extension no setter

bool get isNull

Whether this value corresponds to JavaScript null.

INFO

Currently, there is no way to distinguish between JavaScript undefined and JavaScript null when compiling to Wasm. Therefore, this getter should only be used for code that compiles to JavaScript and will throw when compiling to Wasm.

Available on JSAny, provided by the NullableUndefineableJSAnyExtension extension

Implementation

external bool get isNull;

isTruthy extension no setter

JSBoolean get isTruthy

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

Available on JSAny, provided by the JSAnyOperatorExtension extension

Implementation

external JSBoolean get isTruthy;

isUndefined extension no setter

bool get isUndefined

Whether this value corresponds to JavaScript undefined.

INFO

Currently, there is no way to distinguish between JavaScript undefined and JavaScript null when compiling to Wasm. Therefore, this getter should only be used for code that compiles to JavaScript and will throw when compiling to Wasm.

Available on JSAny, provided by the NullableUndefineableJSAnyExtension extension

Implementation

external bool get isUndefined;

isUndefinedOrNull extension no setter

bool get isUndefinedOrNull

Available on JSAny, provided by the NullableUndefineableJSAnyExtension extension

Implementation

bool get isUndefinedOrNull => this == null;

key no setter

String? get key

Returns the shared symbol key from the global symbol registry for this symbol (as registered with forKey), if this symbol was created with JSSymbol.forKey.

Implementation

@Since('3.11')
String? get key => _keyFor(this);

not extension no setter

JSBoolean get not

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

Available on JSAny, provided by the JSAnyOperatorExtension extension

Implementation

external JSBoolean get not;

runtimeType no setter inherited

Type get runtimeType

A representation of the runtime type of the object.

Inherited from Object.

Implementation

external Type get runtimeType;

Methods

add() extension

JSAny add(JSAny? any)

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

Available on JSAny, provided by the JSAnyOperatorExtension extension

Implementation

external JSAny add(JSAny? any);

and() extension

JSAny? and(JSAny? any)

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

Available on JSAny, provided by the JSAnyOperatorExtension extension

Implementation

external JSAny? and(JSAny? any);

dartify() extension

Object? dartify()

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.

INFO

Prefer using the specific conversion member like toDart if you know the JavaScript type as this method may perform many type-checks. You should generally call this method with values that only contain JSON-like values as the conversion may be platform- and compiler-specific otherwise.

Available on JSAny, provided by the JSAnyUtilityExtension extension

Implementation

// 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();

divide() extension

JSAny divide(JSAny? any)

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

Available on JSAny, provided by the JSAnyOperatorExtension extension

Implementation

external JSAny divide(JSAny? any);

equals() extension

JSBoolean equals(JSAny? any)

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

Available on JSAny, provided by the JSAnyOperatorExtension extension

Implementation

external JSBoolean equals(JSAny? any);

exponentiate() extension

JSAny exponentiate(JSAny? any)

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

Available on JSAny, provided by the JSAnyOperatorExtension extension

Implementation

external JSAny exponentiate(JSAny? any);

greaterThan() extension

JSBoolean greaterThan(JSAny? any)

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

Available on JSAny, provided by the JSAnyOperatorExtension extension

Implementation

external JSBoolean greaterThan(JSAny? any);

greaterThanOrEqualTo() extension

JSBoolean greaterThanOrEqualTo(JSAny? any)

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

Available on JSAny, provided by the JSAnyOperatorExtension extension

Implementation

external JSBoolean greaterThanOrEqualTo(JSAny? any);

instanceof() extension

bool instanceof(JSFunction constructor)

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

Available on JSAny, provided by the JSAnyUtilityExtension extension

Implementation

external bool instanceof(JSFunction constructor);

instanceOfString() extension

bool instanceOfString(String constructorName)

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

Implementation

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

bool isA<T extends JSAny?>()

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

Implementation

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

lessThan() extension

JSBoolean lessThan(JSAny? any)

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

Available on JSAny, provided by the JSAnyOperatorExtension extension

Implementation

external JSBoolean lessThan(JSAny? any);

lessThanOrEqualTo() extension

JSBoolean lessThanOrEqualTo(JSAny? any)

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

Available on JSAny, provided by the JSAnyOperatorExtension extension

Implementation

external JSBoolean lessThanOrEqualTo(JSAny? any);

modulo() extension

JSAny modulo(JSAny? any)

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

Available on JSAny, provided by the JSAnyOperatorExtension extension

Implementation

external JSAny modulo(JSAny? any);

multiply() extension

JSAny multiply(JSAny? any)

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

Available on JSAny, provided by the JSAnyOperatorExtension extension

Implementation

external JSAny multiply(JSAny? any);

noSuchMethod() inherited

dynamic noSuchMethod(Invocation invocation)

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.

Implementation

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

notEquals() extension

JSBoolean notEquals(JSAny? any)

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

Available on JSAny, provided by the JSAnyOperatorExtension extension

Implementation

external JSBoolean notEquals(JSAny? any);

or() extension

JSAny? or(JSAny? any)

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

Available on JSAny, provided by the JSAnyOperatorExtension extension

Implementation

external JSAny? or(JSAny? any);

strictEquals() extension

JSBoolean strictEquals(JSAny? any)

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

Available on JSAny, provided by the JSAnyOperatorExtension extension

Implementation

external JSBoolean strictEquals(JSAny? any);

strictNotEquals() extension

JSBoolean strictNotEquals(JSAny? any)

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

Available on JSAny, provided by the JSAnyOperatorExtension extension

Implementation

external JSBoolean strictNotEquals(JSAny? any);

subtract() extension

JSAny subtract(JSAny? any)

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

Available on JSAny, provided by the JSAnyOperatorExtension extension

Implementation

external JSAny subtract(JSAny? any);

toString() inherited

String toString()

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.

Implementation

external String toString();

typeofEquals() extension

bool typeofEquals(String typeString)

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

Available on JSAny, provided by the JSAnyUtilityExtension extension

Implementation

external bool typeofEquals(String typeString);

unsignedRightShift() extension

JSNumber unsignedRightShift(JSAny? any)

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

Available on JSAny, provided by the JSAnyOperatorExtension extension

Implementation

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

Operators

operator ==() inherited

bool operator ==(Object other)

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.

Implementation

external bool operator ==(Object other);

Static Properties

asyncIterator no setter

JSSymbol get asyncIterator

See Symbol.asyncIterator.

Implementation

@Since('3.11')
external static JSSymbol get asyncIterator;

hasInstance no setter

JSSymbol get hasInstance

See Symbol.hasInstance.

Implementation

@Since('3.11')
external static JSSymbol get hasInstance;

isConcatSpreadable no setter

JSSymbol get isConcatSpreadable

See Symbol.isConcatSpreadable.

Implementation

@Since('3.11')
external static JSSymbol get isConcatSpreadable;

iterator no setter

JSSymbol get iterator

See Symbol.iterator.

Implementation

@Since('3.11')
external static JSSymbol get iterator;

match no setter

JSSymbol get match

See Symbol.match.

Implementation

@Since('3.11')
external static JSSymbol get match;

matchAll no setter

JSSymbol get matchAll

See Symbol.matchAll.

Implementation

@Since('3.11')
external static JSSymbol get matchAll;

replace no setter

JSSymbol get replace

See Symbol.replace.

Implementation

@Since('3.11')
external static JSSymbol get replace;

search no setter

JSSymbol get search

See Symbol.search.

Implementation

@Since('3.11')
external static JSSymbol get search;

species no setter

JSSymbol get species

See Symbol.species.

Implementation

@Since('3.11')
external static JSSymbol get species;

split no setter

JSSymbol get split

See Symbol.split.

Implementation

@Since('3.11')
external static JSSymbol get split;

toPrimitive no setter

JSSymbol get toPrimitive

See Symbol.toPrimitive.

Implementation

@Since('3.11')
external static JSSymbol get toPrimitive;

toStringTag no setter

JSSymbol get toStringTag

See Symbol.toStringTag.

Implementation

@Since('3.11')
external static JSSymbol get toStringTag;

unscopables no setter

JSSymbol get unscopables

See Symbol.unscopables.

Implementation

@Since('3.11')
external static JSSymbol get unscopables;

Static Methods

forKey()

JSSymbol forKey(String key)

Searches for an existing symbol in a runtime-wide symbol registry with the given key and returns it if found.

Otherwise, creates a new symbol with this key, adds it to the global registry, and returns it.

Implementation

@Since('3.11')
@JS('for')
external static JSSymbol forKey(String key);