Add a `dart:js_interop` API that can determine if an `Object` is a JS value

[srujzs]

Historically, it was common for users to treat JS values through interop as Dart types and not JS types, mainly because the concept of "JS types" did not exist yet. So, values may flow through as Object or dynamic to other parts of code. This code may accept both a Dart and a JS value, making it difficult to determine how to treat such a value without some way of distinguishing the two runtimes.

The canonical way to type-check Dart objects is to use is, but we don't want users using that if it's a JS value, as it may give inconsistent values. This is partially why we have the invalid_runtime_check_with_js_interop_types lint.

The canonical way to type-check JS values is to use isA, but that requires a cast to JSAny in the first place. This cast will always succeed when compiling to JS (because it's Object under-the-hood there), but may fail when compiling to Wasm (because it's JSValue). This is our best option today.

So, to determine how to type-check a given Object, it is useful to know whether it's a JS value in the first place. One such mechanism is a compiler-specific external patched API in dart:js_interop.

Some quirks that we might come across:

• Primitive types (String, int/double/num, bool) are both Dart and JS values when compiling to JS. This is not true when compiling to Wasm. We may want to always treat them as JS values for the sake of this API, but users should be aware that they should still type-check for the Dart primitive types when this API returns false so that they handle the Wasm case correctly.
• Dart functions are JS functions in DDC, so the implementation should use the type system internals to differentiate them instead of interop.
• Inconsistencies in our internal type system checks. Hopefully this should be fine in most realistic use cases, but we've seen edge-cases before e.g. DDC treating prototypes of compiled Dart objects as Dart objects whereas dart2js and dart2wasm do not. I expect dart2wasm should generally have no issues with this check due to the boxing.
• We may want to modify the invalid_runtime_check_with_js_interop_types check to account for this new API e.g. pointing users to this API when they do a is JSAny check.

[gmpassos]

Any update on this?

[gmpassos]

FYI: @kevmoo @mit-mit

We urgently need something like the extension below, with official support for each platform:

extension ObjectToJSAnyNullableExtension on Object? {
  bool get isJSAny;
  bool get isJSObject;
}

NOTE: After discussing this issue with other developers, we concluded that, without a secure way to cast Object to JSAny, the new dart:js_interop is not stable for real-world use cases.

[kevmoo]

@srujzs is the expert here. I will make sure we follow-up this week.

[gmpassos]

@srujzs is the expert here. I will make sure we follow-up this week.

Thanks for the quick response

[srujzs]

I want to get this done before the next stable, for both the JS compilers and dart2wasm.

I don't believe we need isJSObject as long as we can check if something is a JS value. This would then allow you to cast to JSAny? and safely type-check via isA<JSObject>.

[gmpassos]

I agree that isJSObject is not mandatory. However, since most cases of using JSAny.isA<T>() involve a T that is not a primitive, isJSObject can be very useful.

It also provides an opportunity for an optimized implementation of isJSObject. Additionally, it is easier to ensure that an Object is a JSObject, as the primitive implementations of JSAny can be ambiguous depending on the platform.

Therefore, it is much easier to implement isJSObject in cases where isJSAny becomes ambiguous.

I have internally implemented a bool? isJSAny that returns null in cases where the detection is ambiguous. However, for isJSObject, there are no ambiguous cases.

[gmpassos]

FYI: @srujzs

I have published the package js_interop_utils, which includes a temporary implementation of isJSAny and isJSObject until an official Dart implementation becomes available.

bool? get isJSAny {
https://github.com/gmpassos/js_interop_utils/blob/39682fa7dc11e91b03a5390882f4538e304e21c7/lib/src/js_interop_utils_extensions.dart#L9

bool? get isJSObject {
https://github.com/gmpassos/js_interop_utils/blob/39682fa7dc11e91b03a5390882f4538e304e21c7/lib/src/js_interop_utils_extensions.dart#L99

This might help clarify the issues involved in implementing an official version.