Add docs for ExternalDartReference #5668
Conversation
This type exists in 3.4 onwards but isn't a JS type. See dart-lang/sdk#55187 for more details on what the type is.
|
Visit the preview URL for this PR (updated for commit 2409ab4): https://dart-dev--pr5668-addexternaldartreference-45iczn14.web.app |
| @@ -38,6 +38,15 @@ JS types form a natural type hierarchy: | |||
|
|
|||
| You can find the definition of each type in the [`dart:js_interop` API docs]. | |||
|
|
|||
| From Dart 3.4 onwards, there also exists one type in `dart:js_interop` that can | |||
| be used but is *not* a JS type called `ExternalDartReference`. | |||
There was a problem hiding this comment.
"be used" here may be missing context (e.g. used for what purpose?)
| Dart `Object`s through JavaScript. However, `JSBoxedDartObject` wraps the opaque | ||
| reference in a JavaScript object, while `ExternalDartReference` is the reference | ||
| itself and therefore is not a JS type. Use `ExternalDartReference` where | ||
| performance is needed and `JSBoxedDartObject` where a JS type is needed. |
There was a problem hiding this comment.
While correct, I'm not sure if we have an intuition for when "a JS type is needed".
Aside frokm being required by a type signature, are there use-cases we can describe where it makes sense to use one or the other? For example, if you just want to pass references opaquely back and forth and using the reference just as an identity, then ExternalDartReference seems like a good fit. If you however want a reference that can also store data and you want to extend it to add data to that reference, then we recommend using JSBoxedDartObject. However, the latter feels like a strange and uncommon scenario. Are there other scenarios where we would be inclined to use it?
There was a problem hiding this comment.
Yeah, I think needed here is entirely specific to the type signature. It may be "needed" in order to pass the Dart object to an API that accepts a JSAny, or place within a JSArray. I don't see much reason for anyone to actually interact with a JSBoxedDartObject. I added a comment to illustrate what "a JS type is needed" might mean.
| @@ -73,7 +82,7 @@ Generally, the conversion table looks like the following: | |||
| <div class="table-wrapper" markdown="1"> | |||
|
|
|||
| | JS type | Dart type | | |||
There was a problem hiding this comment.
(optional, maybe something to consider as a separate follow up change)
I'm curious about generalizing this table to include ExternalDartReference. Maybe if we were to rename "JS type" to something more general, we could?
At first I was going to suggest "Interop type", but I believe we use JS-type and interop-type interchangingly.
There was a problem hiding this comment.
I believe we use JS-type and interop-type interchangingly.
We actually don't use them interchangeably. I think JS types are interop types, but not all interop types are JS types. From the Usage page:
Interop types are either a "JS type" provided by Dart or an extension type wrapping an interop type.
Edit: (Forgot to conclude) So if ExternalDartReference fits that more general definition of interop types, then I think we could change the column name to Interop types. That would allow an other conversions of note to be included too (if there are any)
There was a problem hiding this comment.
Right - JS types are a subset of interop types.
I thought about initially putting ExternalDartReference here, but the name gave me pause. Interop types works and lets it fit in nicely.
There was a problem hiding this comment.
nit: I changed this to dart:js_interop type instead of just Interop type so that it avoids contradicting the above definition for ExternalDartReference.
This type was added as part of dart-lang/sdk#55187 to dart:js_interop for a faster alternative to JSBoxedDartObject, so we should add some documentation on it.