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.

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

lib/src/dom/event_timing.dart

@@ -14,7 +14,6 @@ library;
 import 'dart:js_interop';
 
 import 'dom.dart';
-import 'hr_time.dart';
 import 'performance_timeline.dart';
 
 /// The `PerformanceEventTiming` interface of the Event Timing API provides
@@ -34,14 +33,14 @@ extension type PerformanceEventTiming._(JSObject _)
   /// The read-only **`processingStart`** property returns the time at which
   /// event dispatch started. This is when event handlers are about to be
   /// executed.
-  external DOMHighResTimeStamp get processingStart;
+  external double get processingStart;
 
   /// The read-only **`processingEnd`** property returns the time the last event
   /// handler finished executing.
   ///
   /// It's equal to [PerformanceEventTiming.processingStart] when there are no
   /// such event handlers.
-  external DOMHighResTimeStamp get processingEnd;
+  external double get processingEnd;
 
   /// The read-only **`cancelable`** property returns the associated event's
   /// [`cancelable`](https://developer.mozilla.org/en-US/docs/Web/API/Event/cancelable)

lib/src/dom/gamepad.dart

@@ -14,7 +14,6 @@ library;
 import 'dart:js_interop';
 
 import 'dom.dart';
-import 'hr_time.dart';
 
 typedef GamepadMappingType = String;
 
@@ -84,7 +83,7 @@ extension type Gamepad._(JSObject _) implements JSObject {
   /// newer values will always be greater than or equal to older values.
   ///
   /// > **Note:** This property is not currently supported anywhere.
-  external DOMHighResTimeStamp get timestamp;
+  external double get timestamp;
 
   /// The **`Gamepad.mapping`** property of the
   /// [Gamepad] interface returns a string indicating whether the browser has
@@ -166,7 +165,7 @@ extension type GamepadButton._(JSObject _) implements JSObject {
   /// The values are normalized to the range `0.0` — `1.0`, with
   /// `0.0` representing a button that is not pressed, and 1.0 representing a
   /// button that is fully pressed.
-  external num get value;
+  external double get value;
 }
 
 /// The **`GamepadHapticActuator`** interface of the

lib/src/dom/generic_sensor.dart

@@ -14,7 +14,6 @@ library;
 import 'dart:js_interop';
 
 import 'dom.dart';
-import 'hr_time.dart';
 import 'html.dart';
 import 'webidl.dart';
 
@@ -73,7 +72,7 @@ extension type Sensor._(JSObject _) implements EventTarget, JSObject {
   ///
   /// Because [Sensor] is a base class, `timestamp` may only be read
   /// from one of its derived classes.
-  external DOMHighResTimeStamp? get timestamp;
+  external double? get timestamp;
   external EventHandler get onreading;
   external set onreading(EventHandler value);
   external EventHandler get onactivate;
@@ -84,7 +83,7 @@ extension type Sensor._(JSObject _) implements EventTarget, JSObject {
 extension type SensorOptions._(JSObject _) implements JSObject {
   external factory SensorOptions({num frequency});
 
-  external num get frequency;
+  external double get frequency;
   external set frequency(num value);
 }
 

lib/src/dom/geolocation.dart

@@ -113,12 +113,12 @@ extension type GeolocationCoordinates._(JSObject _) implements JSObject {
   /// interface is a strictly positive `double` representing the accuracy, with
   /// a 95% confidence level, of the [GeolocationCoordinates.latitude] and
   /// [GeolocationCoordinates.longitude] properties expressed in meters.
-  external num get accuracy;
+  external double get accuracy;
 
   /// The **`latitude`** read-only property of the [GeolocationCoordinates]
   /// interface is a `double` representing the latitude of the position in
   /// decimal degrees.
-  external num get latitude;
+  external double get latitude;
 
   /// The **`longitude`** read-only property of the [GeolocationCoordinates]
   /// interface is a number which represents the longitude of a geographical
@@ -127,22 +127,22 @@ extension type GeolocationCoordinates._(JSObject _) implements JSObject {
   /// measurement, the `GeolocationCoordinates` object is part of the
   /// [GeolocationPosition] interface, which is the object type returned by
   /// Geolocation API functions that obtain and return a geographical position.
-  external num get longitude;
+  external double get longitude;
 
   /// The **`altitude`** read-only property of the [GeolocationCoordinates]
   /// interface is a `double` representing the altitude of the position in
   /// meters above the
   /// [WGS84](https://gis-lab.info/docs/nima-tr8350.2-wgs84fin.pdf) ellipsoid
   /// (which defines the nominal sea level surface). This value is `null` if the
   /// implementation cannot provide this data.
-  external num? get altitude;
+  external double? get altitude;
 
   /// The **`altitudeAccuracy`** read-only property of the
   /// [GeolocationCoordinates] interface is a strictly positive `double`
   /// representing the accuracy, with a 95% confidence level, of the `altitude`
   /// expressed in meters. This value is `null` if the implementation doesn't
   /// support measuring altitude.
-  external num? get altitudeAccuracy;
+  external double? get altitudeAccuracy;
 
   /// The **`heading`** read-only property of the [GeolocationCoordinates]
   /// interface is a `double` representing the direction in which the device is
@@ -152,13 +152,13 @@ extension type GeolocationCoordinates._(JSObject _) implements JSObject {
   /// degrees and west is `270` degrees). If [GeolocationCoordinates.speed] is
   /// `0`, `heading` is `NaN`. If the device is not able to provide heading
   /// information, this value is `null`.
-  external num? get heading;
+  external double? get heading;
 
   /// The **`speed`** read-only property of the [GeolocationCoordinates]
   /// interface is a `double` representing the velocity of the device in meters
   /// per second. This value is `null` if the implementation is not able to
   /// measure it.
-  external num? get speed;
+  external double? get speed;
 }
 
 /// The **`GeolocationPositionError`** interface represents the reason of an