JSAnyUtilityExtension

extension JSAnyUtilityExtension on JSAny?

Common utility functions that are useful for any JavaScript value.

Methods

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

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

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