diff --git a/index.bs b/index.bs index 38461673..809aaab6 100644 --- a/index.bs +++ b/index.bs @@ -757,38 +757,50 @@ Instead, you will want to stick with one of: : bigint :: When the possible integer values range more broadly than JavaScript numbers can accurately represent -Additionally, you can combine any of the above with an extra line in your algorithm to validate -that the number is within the expected domain-specific range, and throwing or performing other -actions in response. (While it is very rarely appropriate to modify author input by taking it -modulo 65536, it might be appropriate to take it modulo 360, for example.) - -A special case of domain-specific validation, which Web IDL already has you covered for, is the -0–255 range. This can be written as [EnforceRange] octet: any JavaScript number in -the range 0–255, throwing a TypeError outside the range and rounding inside of it. -(And indeed, if it turns out that the other power-of-two ranges are semantically meaningful for -your domain, such that you want the modulo or range-checking behavior, feel free to use them.) +Additionally, you can combine any of the above with an extra line in your +algorithm to validate that the number is within the expected domain-specific +range, and throwing or performing other actions in response. (While it is very +rarely appropriate to modify author input by taking it modulo 65536, it might be +appropriate to take it modulo 360, for example.) + +A special case of domain-specific validation, which Web IDL already has you +covered for, is the 0–255 range. This can be written as [EnforceRange] +octet: any JavaScript number in the range 0–255, throwing a TypeError outside the range and rounding inside of it. +(And indeed, if it turns out that the other power-of-two ranges are semantically +meaningful for your domain, such that you want the modulo or range-checking +behavior, feel free to use them.)
-Those coming from other languages should carefully note that despite their names, -long long and unsigned long long only have 53 bits of precision, and -not 64. +Those coming from other languages should carefully note that despite their +names, long long and unsigned long long only have 53 +bits of precision, and not 64.
-bigint is recommended to be used only in circumstances where a [EnforceRange] long long -or [EnforceRange] unsigned long long would not work in terms of expressivity: that is, only when values -greater than 253 or less than -253 are expected. In particular, APIs should not use the bigint -type simply because the input is an integer—bigint is for big integers (hence the name!). - -Transparent support for inputs being either JavaScript Number of BigInt types is discouraged, unless there is a -domain-specific requirement to support it. As far as ergonomics, JavaScript developers are expected to keep track -of whether their values are Numbers or BigInts. Sloppiness or implicit conversions here could lead to a loss of -precision, defeating the purpose of using BigInt. +bigint is recommended to be used only in circumstances +where a [EnforceRange] long long or [EnforceRange] unsigned +long long would not work in terms of expressivity: that is, only when +values greater than 253 or less than -253 are expected. In +particular, APIs should not use the bigint type simply because the +input is an integer—bigint is for big integers (hence the +name!). + +Transparent support for inputs being either JavaScript Number of BigInt types is +discouraged, unless there is a domain-specific requirement to support it. As far +as ergonomics, JavaScript developers are expected to keep track of whether their +values are Numbers or BigInts. Sloppiness or implicit conversions here could +lead to a loss of precision, defeating the purpose of using BigInt. + +Further, try to resist doubling up the surface area of an API in order to +provide both `BigInt` and `Number` variants of an API. As an API designer, +consider it your job to chose the correct numeric type for the feature being +exposed.

Use milliseconds for time measurement

-Any web API that accepts a time measurement should do so in milliseconds. This is a tradition -stemming from setTimeout and the Date API, and carried through since -then. +Any web API that accepts a time measurement should do so in milliseconds. This +is a tradition stemming from setTimeout and the +Date API, and carried through since then. Even if seconds (or some other unit) are more natural in the domain of an API, sticking with milliseconds ensures interoperability with the rest of the platform, allowing easy arithmetic with @@ -971,7 +983,7 @@ Please take advantage of these other excellent resources in your design process:

Polyfills

-Polyfills can be hugely beneficial in helping to roll out new features to the web platform. The +Polyfills can be hugely beneficial in helping to roll out new features to the web platform. The Technical Architecture Group finding on Polyfills and the Evolution of the Web offers guidance that should be considered in the development of new features, notably: