Emit double as return value instead of num (#256)

Emit double as return value instead of num

Closes #57

In cases where the return type is known to be a double
value, prefer double over num so users don't try and
downcast the type, which won't work consistently on
all compilers. In order to do this, _typeReference is
amended to take an extra option 'returnType' which
determines if the `_RawType` is used in a return type
context.

Author: srujzs

CHANGELOG.md

@@ -15,6 +15,12 @@
 - Added `onUnload` event stream to `ElementEventGetters` extension methods.
 - Expose `ElementStream` as a public class.
 - Require Dart `^3.4.0`.
+- APIs that return a double value now return `double` instead of `num`. This is
+  to avoid users accidentally downcasting `num`, which has different semantics
+  depending on whether you compile to JS or Wasm. See issue [#57][] for more
+  details.
+
+[#57]: https://github.com/dart-lang/web/issues/57
 
 ## 0.5.1
 

lib/src/dom/battery_status.dart

@@ -50,7 +50,7 @@ extension type BatteryManager._(JSObject _) implements EventTarget, JSObject {
   /// > **Note:** Even if the time returned is precise to the second,
   /// > browsers round them to a higher interval
   /// > (typically to the closest 15 minutes) for privacy reasons.
-  external num get chargingTime;
+  external double get chargingTime;
 
   /// The **`dischargingTime`** read-only property of the [BatteryManager]
   /// interface indicates the amount of time, in seconds, that remains until the
@@ -63,7 +63,7 @@ extension type BatteryManager._(JSObject _) implements EventTarget, JSObject {
   /// > **Note:** Even if the time returned is precise to the second, browsers
   /// > round them to a higher
   /// > interval (typically to the closest 15 minutes) for privacy reasons.
-  external num get dischargingTime;
+  external double get dischargingTime;
 
   /// The **`level`** read-only property of the [BatteryManager] interface
   /// indicates the current battery charge level as a value between `0.0` and
@@ -74,7 +74,7 @@ extension type BatteryManager._(JSObject _) implements EventTarget, JSObject {
   /// report the battery status information.
   /// When its value changes, the [BatteryManager.levelchange_event] event is
   /// fired.
-  external num get level;
+  external double get level;
   external EventHandler get onchargingchange;
   external set onchargingchange(EventHandler value);
   external EventHandler get onchargingtimechange;

lib/src/dom/cookie_store.dart

@@ -94,7 +94,7 @@ extension type CookieInit._(JSObject _) implements JSObject {
   external set name(String value);
   external String get value;
   external set value(String value);
-  external DOMHighResTimeStamp? get expires;
+  external double? get expires;
   external set expires(DOMHighResTimeStamp? value);
   external String? get domain;
   external set domain(String? value);
@@ -142,7 +142,7 @@ extension type CookieListItem._(JSObject _) implements JSObject {
   external set domain(String? value);
   external String get path;
   external set path(String value);
-  external DOMHighResTimeStamp? get expires;
+  external double? get expires;
   external set expires(DOMHighResTimeStamp? value);
   external bool get secure;
   external set secure(bool value);

lib/src/dom/css_animations.dart

@@ -43,7 +43,7 @@ extension type AnimationEvent._(JSObject _) implements Event, JSObject {
   /// `elapsedTime` is `0.0` unless there was a negative value for
   /// , in which case the event will be fired with
   /// `elapsedTime` containing `(-1 * delay)`.
-  external num get elapsedTime;
+  external double get elapsedTime;
 
   /// The **`AnimationEvent.pseudoElement`** read-only property is a
   /// string, starting with `'::'`, containing the name of the
@@ -65,7 +65,7 @@ extension type AnimationEventInit._(JSObject _) implements EventInit, JSObject {
 
   external String get animationName;
   external set animationName(String value);
-  external num get elapsedTime;
+  external double get elapsedTime;
   external set elapsedTime(num value);
   external String get pseudoElement;
   external set pseudoElement(String value);

lib/src/dom/css_paint_api.dart

@@ -116,7 +116,7 @@ extension type PaintRenderingContext2D._(JSObject _) implements JSObject {
   ]);
   external void setLineDash(JSArray<JSNumber> segments);
   external JSArray<JSNumber> getLineDash();
-  external num get globalAlpha;
+  external double get globalAlpha;
   external set globalAlpha(num value);
   external String get globalCompositeOperation;
   external set globalCompositeOperation(String value);
@@ -128,26 +128,26 @@ extension type PaintRenderingContext2D._(JSObject _) implements JSObject {
   external set strokeStyle(JSAny value);
   external JSAny get fillStyle;
   external set fillStyle(JSAny value);
-  external num get shadowOffsetX;
+  external double get shadowOffsetX;
   external set shadowOffsetX(num value);
-  external num get shadowOffsetY;
+  external double get shadowOffsetY;
   external set shadowOffsetY(num value);
-  external num get shadowBlur;
+  external double get shadowBlur;
   external set shadowBlur(num value);
   external String get shadowColor;
   external set shadowColor(String value);
-  external num get lineWidth;
+  external double get lineWidth;
   external set lineWidth(num value);
   external CanvasLineCap get lineCap;
   external set lineCap(CanvasLineCap value);
   external CanvasLineJoin get lineJoin;
   external set lineJoin(CanvasLineJoin value);
-  external num get miterLimit;
+  external double get miterLimit;
   external set miterLimit(num value);
-  external num get lineDashOffset;
+  external double get lineDashOffset;
   external set lineDashOffset(num value);
 }
 extension type PaintSize._(JSObject _) implements JSObject {
-  external num get width;
-  external num get height;
+  external double get width;
+  external double get height;
 }

lib/src/dom/css_transitions.dart

@@ -39,7 +39,7 @@ extension type TransitionEvent._(JSObject _) implements Event, JSObject {
   /// seconds,
   /// when this event fired. This value is not affected by the
   /// property.
-  external num get elapsedTime;
+  external double get elapsedTime;
 
   /// The **`TransitionEvent.pseudoElement`** read-only property is a
   /// string, starting with `'::'`, containing the name of the
@@ -63,7 +63,7 @@ extension type TransitionEventInit._(JSObject _)
 
   external String get propertyName;
   external set propertyName(String value);
-  external num get elapsedTime;
+  external double get elapsedTime;
   external set elapsedTime(num value);
   external String get pseudoElement;
   external set pseudoElement(String value);

lib/src/dom/css_typed_om.dart

@@ -302,7 +302,7 @@ extension type CSSUnitValue._(JSObject _) implements CSSNumericValue, JSObject {
 
   /// The **`CSSUnitValue.value`** property of the
   /// [CSSUnitValue] interface returns a double indicating the number of units.
-  external num get value;
+  external double get value;
   external set value(num value);
 
   /// The **`CSSUnitValue.unit`** read-only property

lib/src/dom/cssom_view.dart

@@ -33,9 +33,9 @@ extension type ScrollToOptions._(JSObject _)
     num top,
   });
 
-  external num get left;
+  external double get left;
   external set left(num value);
-  external num get top;
+  external double get top;
   external set top(num value);
 }
 
@@ -248,41 +248,41 @@ extension type VisualViewport._(JSObject _) implements EventTarget, JSObject {
   /// returns the offset of the left edge of the visual viewport from the left
   /// edge of the layout viewport in CSS pixels, or `0` if current document is
   /// not fully active.
-  external num get offsetLeft;
+  external double get offsetLeft;
 
   /// The **`offsetTop`** read-only property of the [VisualViewport] interface
   /// returns the offset of the top edge of the visual viewport from the top
   /// edge of the layout viewport in CSS pixels, or `0` if current document is
   /// not fully active.
-  external num get offsetTop;
+  external double get offsetTop;
 
   /// The **`pageLeft`** read-only property of the [VisualViewport] interface
   /// returns the x coordinate of the left edge of the visual viewport relative
   /// to the initial containing block origin, in CSS pixels, or `0` if current
   /// document is not fully active.
-  external num get pageLeft;
+  external double get pageLeft;
 
   /// The **`pageTop`** read-only property of the [VisualViewport] interface
   /// returns the y coordinate of the top edge of the visual viewport relative
   /// to the initial containing block origin, in CSS pixels, or `0` if current
   /// document is not fully active.
-  external num get pageTop;
+  external double get pageTop;
 
   /// The **`width`** read-only property of the [VisualViewport] interface
   /// returns the width of the visual viewport, in CSS pixels, or `0` if current
   /// document is not fully active.
-  external num get width;
+  external double get width;
 
   /// The **`height`** read-only property of the [VisualViewport] interface
   /// returns the height of the visual viewport, in CSS pixels, or `0` if
   /// current document is not fully active.
-  external num get height;
+  external double get height;
 
   /// The **`scale`** read-only property of the [VisualViewport] interface
   /// returns the pinch-zoom scaling factor applied to the visual viewport, or
   /// `0` if current document is not fully active, or `1` if there is no output
   /// device.
-  external num get scale;
+  external double get scale;
   external EventHandler get onresize;
   external set onresize(EventHandler value);
   external EventHandler get onscroll;

lib/src/dom/dom.dart

@@ -19,7 +19,6 @@ import 'cssom.dart';
 import 'cssom_view.dart';
 import 'fullscreen.dart';
 import 'geometry.dart';
-import 'hr_time.dart';
 import 'html.dart';
 import 'selection_api.dart';
 import 'svg.dart';
@@ -286,7 +285,7 @@ extension type Event._(JSObject _) implements JSObject {
 
   /// The **`timeStamp`** read-only property of the [Event] interface returns
   /// the time (in milliseconds) at which the event was created.
-  external DOMHighResTimeStamp get timeStamp;
+  external double get timeStamp;
 }
 extension type EventInit._(JSObject _) implements JSObject {
   external factory EventInit({
@@ -3406,7 +3405,7 @@ extension type Element._(JSObject _) implements Node, JSObject {
   ///
   /// > **Warning:** On systems using display scaling, `scrollTop` may give you
   /// > a decimal value.
-  external num get scrollTop;
+  external double get scrollTop;
   external set scrollTop(num value);
 
   /// The **`Element.scrollLeft`** property gets or sets the number
@@ -3432,7 +3431,7 @@ extension type Element._(JSObject _) implements Node, JSObject {
   /// > **Warning:** On systems using display scaling, `scrollLeft` may give you
   /// > a decimal
   /// > value.
-  external num get scrollLeft;
+  external double get scrollLeft;
   external set scrollLeft(num value);
 
   /// The **`Element.scrollWidth`** read-only property is a
@@ -5253,7 +5252,7 @@ extension type XPathResult._(JSObject _) implements JSObject {
   /// The read-only **`numberValue`** property of the
   /// [XPathResult] interface returns the numeric value of a result with
   /// [XPathResult.resultType] being `NUMBER_TYPE`.
-  external num get numberValue;
+  external double get numberValue;
 
   /// The read-only **`stringValue`** property of the
   /// [XPathResult] interface returns the string value of a result with

lib/src/dom/encrypted_media.dart

@@ -171,7 +171,7 @@ extension type MediaKeySession._(JSObject _) implements EventTarget, JSObject {
   /// measured in milliseconds since January 1, 1970, UTC. This value may change
   /// during a
   /// session lifetime, such as when an action triggers the start of a window.
-  external num get expiration;
+  external double get expiration;
 
   /// The `MediaKeySession.closed` read-only property returns a
   /// `Promise` signaling when a [MediaKeySession] closes. This