whatwg / webidl

Web IDL Standard

This repository hosts the Web IDL Standard.

Code of conduct

We are committed to providing a friendly, safe, and welcoming environment for all. Please read and respect the WHATWG Code of Conduct.

Contributing

Good first issues are labeled as a short good first issue.

IDL generally follows the WHATWG Contributor Guidelines and WHATWG Committer Guidelines, except as otherwise noted.

Markup

The specification is written in Bikeshed, plus the Ecmarkup tags <emu-val>, <emu-t>, and <emu-nt>.

Building "locally"

For quick local iteration, run make. To verify your changes locally, run npm install and make deploy. See more in the WHATWG Contributor Guidelines.

Filing issues elsewhere

Breaking changes should be filed against:

• Rendering engines
  • Gecko
  • WebKit
  • Chromium
• web-platform-tests
• idlharness.js (used by testharness.js to run IDL tests)
• Reffy (scrapes IDL from specs for reffy-reports and web-platform-tests)

Syntax changes should be filed against the following parsers:

• widlparser (used by Bikeshed)
• WebIDL parser (used by idlharness.js)
• TypeScript and JavaScript lib generator

webidl's Issues

iterable interface iterators should return the actual key (or the value if there is no key) not an index

See https://bugzilla.mozilla.org/show_bug.cgi?id=1085293#c10. Basically, two-type iterables should act like Map and one-type ones should act like Set, instead of acting like Array.

Close this issue tracker

One is enough, and bugzilla has been in use longer.

"it is not possible for a single platform object to implement both interfaces"

Apparently two IDL interface types are distinguishable if all of the following hold

• The two identified interfaces are not the same
• It is not possible for a single platform object to implement both interfaces
• It is not the case that both are callback interfaces.

This second condition is very confusing. I can think of two possible interpretations:

Interpretation A

[NoInterfaceObject] interface Foo {};
[NoInterfaceObject] interface Bar {};

interface Baz {};
Baz implements Foo;
Baz implements Bar;

Baz implements both Foo and Bar, so Foo and Bar are not distinguishable. (Contrapositive of the given statement.)

Interpretation B

[NoInterfaceObject] interface Foo { readonly attribute x; };
[NoInterfaceObject] interface Bar { attribute x; };

interface Baz {};
Baz implements Foo;
Baz implements Bar; // not allowed

It is not possible to implement both Foo and Bar at the same time, so they are distinguishable.

Discussion

Both of these interpretations kind of suck.

Interpretation A is a very nonlocal definition. To determine if A and B are distinguishable, you have to look at all interfaces in the web platform, and find out if any of them implement both A and B. (I think something that extends A and implements B would also work, or vice-versa.) This means A and B's distinguishability can change at any time.

Interpretation B is very implicit. It comes down to finding all places in the spec that prohibit implementing a given interface. In this case I found the condition

For a given interface, there MUST NOT be any member defined on any of its consequential interfaces whose identifier is the same as any other member defined on any of those consequential interfaces or on the original interface itself.

but there are others, e.g. the no-cycles condition.

Which is it? And, is this actually implementable, or implemented by existing binding layers?

MapClass should not put Map.prototype in the prototype chain

[MapClass] should not put Map.prototype in the prototype chain, since all the Map.prototype methods will throw on such objects (since they don't create objects with [[MapData]]). Even if [[MapData]] was added, the algorithms specified for [MapClass] methods don't use [[MapData]].

[MapClass] should be a macro for adding a few default methods that let the class in question quack like a map, and not some kind of weird way of creating an object that shadows all the Map methods with versions of them that have different, incompatible semantics.

Error in SerializerRest production

The SerializerRest production currently reads:

[31] SerializerRest →
    OperationRest
  | "=" SerializationPattern 
  | ε

which appears not to match the final semicolon present on all InterfaceMembers.

I believe it should read:

[31] SerializerRest →
    OperationRest
  | "=" SerializationPattern ";"
  | ";"

(OperationRest contains the semicolon.)

By the way, I appreciate that the grammar is structured to be suitable for use as a parsing expression grammar.

[SameObject]/[NewObject] on Promise-type attributes should be allowed

Because Promise types are reference types, the [SameObject] extended attribute should be permitted for use with them. In the current spec, they are forbidden by the restriction:

4.3.15. SameObject

The [SameObject] extended attribute MUST NOT be used on anything other than a read only attribute whose type is an interface type or object.

(Unless Promise is to be understood as an interface type.)

Promise bits in various algorithms refer to the wrong objects.

Things like "O" when they mean the operation, or "operation" when they mean attribute.

provide clearer advice about USVString vs. DOMString

In w3ctag/design-reviews#87 (comment) (see also the following comment) we had a brief discussion about USVString vs. DOMString. This seems like a somewhat tricky (in that it's easy to get wrong) API design issue, and the current wording in WebIDL isn't particularly clear.

http://heycam.github.io/webidl/#idl-USVString currently says:

Specifications SHOULD only use USVString for APIs that perform text processing and need a string of Unicode scalar values to operate on. Most APIs that use strings should instead be using DOMString, which does not make any interpretations of the code units in the string. When in doubt, use DOMString.

This is a bit unclear in a few ways (not clear what "text processing" means; does encoding conversion count?), and doesn't seem to match the other advice being given, e.g., in w3ctag/design-reviews#87 (comment)

This seems like an area where giving clear and consistent advice is important.

Non-optional final dictionary arguments with required fields?

http://heycam.github.io/webidl/#dfn-optional-argument currently says:

If the type of an argument is a dictionary type or a union type that has a dictionary type as one of its flattened member types, and this argument is either the final argument or is followed only by optional arguments, then the argument must be specified as optional. Such arguments are always considered to have a default value of an empty dictionary, unless otherwise specified.

Note: This is to encourage API designs that do not require authors to pass an empty dictionary value when they wish only to use the dictionary’s default values.

If the dictionary has a required field, then the empty-dictionary default wouldn't work, so it seems odd to have to mark the dictionary as optional.

I'm thinking of operations where theOperation(reqVal, {opt1: val1, opt2: val2}) is less clear than theOperation({reqVal: val0, opt1: val1, opt2: val2}), like requestDevice() in the Web Bluetooth spec.

Unenumerable supported property names are badly defined

It is not clear whether they should appear in the result of Object.getOwnPropertyNames. It should probably be clearly stated that they are to.

Cc @heycam

Improve restrictions on attributes/operations when maplike/setlike are used

Two changes:

1. Use of maplike/setlike should not affect static attributes/operations (but should affect constants, as it does now, since those go on the proto too).

2. The mutator methods (clear, add, set, delete) should not be allowed to shadow a method on an inherited interface. But having them on the interface itself or its consequential interfaces should be OK (as now) and just inhibit autogeneration of the method.

Sort out when dictionaries and records should have default values

Right now optional dictionary arguments in trailing position have a default value (empty dictionary) but other optional dictionaries (non-trailing arguments, dictionary members) do not.

This allows spec authors to create APIs in which undefined and empty dictionary have different behavior, which seems suboptimal.

So I'd like to propose that optional dictionaries always have empty dictionary as default value. What that means in practice is not clear. I guess they should use null as the default value. Sadly that's observably different from using {} if someone spews things on Object.prototype...

Anyway, if we do that, then we have one problem: dictionary-to-JS conversion can give ugly results (as described in https://bugzilla.mozilla.org/show_bug.cgi?id=1226475#c0 for example).

To solve that, I propose the following:

1. A dictionary is "elidable" (better-naming-wanted) if it is either empty or only has members whose values are themselves elidable dictionaries.
2. When converting a dictionary to a JS value, skip over members whose values are elidable dictionaries, just like we skip over members that are not present.

For dictionaries that have default values that will still cause them to appear (with those default values), but I can live with that, I think.

@domenic/@heycam Thoughts?

does [Constructor] invocation require 'new' or not (generally)?

Related to issue #55, where in WebIDL does it say (or not say) that invoking constructable interfaces (those interfaces with [NamedConstructor] or one or more [Constructor] extended attributes) should throw when not used with new?

As far as I can tell, in section 4.5.1.1, this is all we get:

 The internal [[Call]] method of the interface object behaves as follows, assuming arg0..n−1 is the list of argument values passed to the constructor, and I is the interface:

1. If I was not declared with a [Constructor] extended attribute, then throw a TypeError.
2. Let id be the identifier of interface I.
3. Initialize S to the effective overload set for constructors with identifier id on interface I and with argument count n.
4. Let <constructor, values> be the result of passing S and arg0..n−1 to the overload resolution algorithm.
5. Let R be the result of performing the actions listed in the description of constructor with values as the argument values.
6. Return the result of converting R to an ECMAScript interface type value I.

Seems like what I'm looking for is wrapped up in step 5, but in my reading this step is deferring to prose for each individual constructor. Would this include requiring the use of new?

In Gecko and Blink, it looks constructable interfaces require new (at least for those I tested, e.g., Image(), XMLHttpRequest(), and in Gecko only ATM: DOMException()).

Bug (sort of)

On the W3C web site, https://w3.org/TR/WEBIDL/ does not resolve to this spec. Rather it points to a much older Candidate Recommendation. Please update that short name to redirect to this short name.

Make the length property for interfaces that support indexed properties mandatory

Currently, interfaces that support indexed properties only make the length property mandatory if they are iterable. The length property is also mentioned as a sufficient condition for the interface to have an @@iterator symbol.

It should probably be made crystal-clear that interfaces that support indexed properties should always have a length attribute.

Have single number type and allow custom ranges

It would be great if WebIDL simply defined a single ES number type and allowed custom ranges. This would greatly simplify the spec by doing away with all the silly types: byte, short, etc. while remaining backwards compatible.

So, something like:

typedef Number[−128..127] Byte;

And would allow for new types:

typedef Number[0..360] Angle;

support [Exposed=Worklet]

For the Worklets spec we'll want to allow [Exposed=Worklet]. See w3c/css-houdini-drafts#120.

Add a PermissionDeniedError

Push-API defines a PermissionDeniedError as: The operation failed because the user denied permission to use the API.

I'd need to use something similar for the Generic Sensor API. Think you could add it to the Spec?

Please prefix getter/setter/callback interface with legacy so it's clear they are

This cannot be fixed soon enough. Apparently we now have RTCIdentityProvider as callback interface? That should never have been added to the platform. We should really mark all the getter/setter/callback interface/etc. stuff as legacy so it's not used.

Add a map type

I'm not sure there is enough critical mass for this yet, but I've seen this come up a few times, so I thought I'd throw it out there...

Some APIs would like to accept a JavaScript object of the form:

   let optionmap = {
      key1 : "stringValue1",
      key2 : "stringValue2",
      keyN : "stringValueN"
   };
   thing.doSomething( optionmap );

Normally, this would be modelled as a dictionary of the form:

   dictionary OptionMap {
      DOMString key1;
      DOMString key2;
      DOMString keyN;
   };
   void doSomething( OptionMap optionmap );

However what is really wanted is not a fixed-length set of dictionary members, but rather an open-ended map of key/value pairs, where the map matches a particular pattern, e.g., in the above example where all keys are a DOMString with a particular unique value, and the value of each key is a DOMString. Another example is the object provided as the second parameter to the built-in Object.create method (a map where the key is the property name and the value is a property descriptor).

I realize that there are other potential "advanced" things that might be desired, such as combining normal dictionary semantics with generic map semantics, and while I think that is interesting, I've not encountered a request for it.

I'm looking for a Type that can be declared so that JS objects can be converted to matching IDL and vice-versa. Re-using the existing 'maplike' declaration, the type could be as simple as:

   map<T> // if we constrain keys to be DOMString
   // or
   map<keyType, T> // If the map's keys can be any type

To wrap up, my initial JavaScript example could be expressed as follows, given the above map<T> type:

   void doSomething( map<DOMString> optionmap );

Grammar issues

I recognized various grammar issues:

1. The production Readonly is used several time but only ReadOnly exists
2. The production ReadonlyMemberRest uses Maplike and Setlike, but only MaplikeRest and SetlikeRest exist
3. The production BufferRelatedType contains the alternative "Int161Array" that should be "Int16Array"

Transferables

I'm wondering if maybe WebIDL should define some kind of "transferable" annotation that more clearly identifies that an object can be used as a structured clone... or maybe should adopt the text from the HTML spec around transferables?

Add [[PlatformBrand]] internal slot to all platform objects

The [[PlatformBrand]] internal slot would be a List (in the ECMAScript sense) of strings. One string per interface on the interface chain of the object. So e.g., Text would have "Text, "CharacterData", "Node", "EventTarget".

This would allow us to be more specific what we mean with instances of something and would also clear up a lot of language in IDL I think.

Need an error for "User refused permission"

In #85, a new "not allowed" error was added. The description says:

"The request is not allowed by the user agent or the platform in the current context."

This does not include the user refusing permission.
We (WEBRTC) have been using SecurityError for this, and were considering switching to this one, (w3c/mediacapture-main#317) - but the description doesn't allow it to be used for users' refusal to allow.

Should we either add an UserRefusedPermission error, or change the description of this one?

@@toStringTag property attributes + general semantics

Editorial note
Should define whether @@toStringTag is writable, enumerable and configurable. All @@toStringTag properties in the ES6 spec are non-writable and non-enumerable, and configurable.

I think we really need to define these. Matching the values on the builtin properties is probably good, because fewer inconsistencies between DOM & JS is good.

The other issue with these properties, is making InterfacePrototype.@@toStringTag === "InterfacePrototype" while Interface.@@toStringTag === "Interface" --- I don't believe we want to give Interface an instance property @@toStringTag, so the alternative is making @@toStringTag a getter which returns a distinct value depending on the receiver --- but this kind of sucks?

So yeah, I don't think we have a good answer for these semantics right now. It's probably worth discussing it a bit

hasOwnProperty fails with ClientRect

Found via debugging some AngularJS:
angular/angular.js#10046

Long story short, hasOwnProperty doesn't work with ClientRect on Safari/Firefox, but does with Chrome.... I'm not sure who's right or which one to go with...

forEach:

function forEach(obj, iterator, context) {
...
  var key;
  for (key in obj) {
    if (obj.hasOwnProperty(key)) {
      iterator.call(context, obj[key], key);
    }
  }
  return obj;
}

In the else statement, the line if (obj.hasOwnProperty(key)) { doesn't work against a ClientRect object in Safari/Firefox so it never sets the data as expected.

JSfiddle (view the console):
http://jsfiddle.net/scts6mcs/5/

Chrome: it copies over:

ClientRect {height: 18, width: 447, left: 0, bottom: 18, right: 447…}
447
Object {height: 18, width: 447, left: 0, bottom: 18, right: 447…}
447 

Safari/Firefox: it fails to copy over the information.

[Log] ClientRect (show, line 45)
[Log] 424 (show, line 46)
[Log] Object (show, line 51)
[Log] undefined (show, line 52) <-- didn't get copied

Error Processing should talk about when to use default values for attributes

The current https://svgwg.org/svg2-draft/implnote.html#ErrorProcessing section doesn't refer to initial/invalid values of attributes, so it's not exactly clear that you're meant to use them when an attribute is invalid in some way. For example looking at https://svgwg.org/svg2-draft/coords.html#ViewBoxAttribute it says that negative values for width/height inside the viewBox are an error, but the Error Processing section linked to doesn't make it clear that the behaviour should be as if the attribute weren't specified (as that's what's specified for the "initial value" in the grey attribute definition box).

Allow unions of dictionaries with a common base dictionary, in return values

From w3c/webrtc-pc#275 (comment)

tl;dr: This avoids the temptation to write "snowball" dictionaries for the purpose of return values.

Member name collisions not from inheritance would be a compiler error.

Additional potential (mis?)use-case w3c/mediacapture-main#211 (comment)

DOMTimeStamp confusion

DOMTimeStamp has a few questionable things I was hoping to get cleared up:

• Because it's unsigned long long, it cannot represent dates before 1970. Is that a desired property for a timestamp?
• It says that it can be either absolute or relative. Do any specs use it for relative timestamps? I have not found any in a quick Google search.
• Why does it exist? This is probably part of a larger conversation regarding the utility of WebIDL's various number types, but, it was pretty confusing to find DOMTimeStamp when I could have just found unsigned long long (or ideally number, which would fix the 1970 restriction).

I'd love to discuss the general problem of number types in WebIDL after I've had time to put together a more concrete proposal, but I am wondering if there's anything we can do to clean up the DOMTimeStamp corner of this mess.

add a type to represent the undefined value

It's too awkward to deal with the undefined value by having to use any. Let's introduce a new type (undefined?) to represent that one value. Some care will be needed to make sure we handle optional arguments, distinguishability, etc. properly.

Define DOMException.prototype.toString() (as this.name + ": " + this.message)

I can't find toString in http://heycam.github.io/webidl/#es-DOMException-prototype-object but it's supported by Blink, Gecko and WebKit as this.name + ": " + this.message. IE11 appears to stringify as either the name or the message, I can't tell because they're the case I tested.

explicitly invoke [[HasOwnProperty]], [[GetProperyOf]], etc. more often

There are many instances in the spec where it says something like "If O has an own property with name P, then ...". Given proxies, we really should be invoking [[HasOwnProperty]] here explicitly, because we'll want to be clear that the proxy handler is invoked. (And it's not really clear whether a proxy has "real" own properties anyway.)

Rename Date to LegacyDateDoNotUse, or at least add a big warning

Per https://groups.google.com/forum/#!topic/mozilla.dev.platform/TiE00xh6Ihg and w3c/webrtc-pc#324. We can update HTML's valueAsDate easily enough.

Legacy callback interface objects are badly defined

Currently, interfaces which are not non-callback interfaces but still have an interface object because they have constants don't have their own name. @bzbarsky suggested during a Mozlando meeting to call them "legacy callback interface objects". The "legacy" part comes from the fact that such interfaces should be avoided anyway.

We should decide whether such legacy callback interface objects (i.e. NodeFilter, the only one such interface like that in the wild) should have a [[HasInstance]] method, and the one for noncallback interface objects can be simplified: steps 2 and 3 are useless for the latter because their "prototype" property is non-configurable, and thus always an object.

Cc @heycam

Distinguishability of buffers source types needs to be defined better

Right now the spec says that "buffer source types" are not distinguishable from each other. But this is clearly wrong, since if that were the case the BufferSource typedef would not be valid.

I believe the right behavior here is that ArrayBuffer is distinguishable from everything that's not ArrayBuffer, ArrayBufferView is distinguishable from everything that's not ArrayBufferView or a typed array type, and a typed array type is distinguishable from everything except ArrayBufferView and itself.

I'm not sure how best to put this in the form of this table, because it would make the table huge...

Perhaps the simplest thing to do is to define that distinguishability works as if these were all interface types with the typed array interfaces considered as inheriting the ArrayBufferView interface.

CheckIterable(V) is not defined in ECMAScript 2015

So, this leaves [at least] the conversion from an ECMAScript value V to a sequence undefined--not sure exactly what CheckIterable() was supposed to do.

My main question: are array-like objects supported (e.g., NodeLists, or Objects with a length and indexed properties), or must they only have a Symbol.iterator? (Or some other thing.)

http://heycam.github.io/webidl/#es-sequence

I checked with Brian Terlson, and he wasn't sure what CheckIterable() was supposed to do either.

Numeric type reform strawperson

Inspired by bug 26901 and @marcoscaceres's #14, I somehow ended up writing a detailed proposal for reforming the numeric types.

WebIDL Numeric Type Reform Strawperson

Motivation

The existing WebIDL numeric types are problematic in a number of ways.

First, they create a misleading parallel with numeric types in other languages, where there is actually a proper numeric type system. This encourages people to use them in situations where they might in other languages, creating non-JavaScript-idiomatic APIs. Most JavaScript APIs will want one of a few things: any numeric value at all; any finite numeric value (possibly restricted to integers); or possibly more complicated validation or clamping logic within a given range. WebIDL does provide some facilities for the latter, but only if your range is based on powers of two; ranges like 0 to 100, -180 to +180, or similar are not supported and require prose.

Second, they have the usual WebIDL problem of using the type system for two different purposes: coercions from JavaScript values, as in the cases of parameter lists and dictionaries, and documentation, as in the case of return values and constants. For the documentation cases, the proliferation of numeric types is simply confusing; declaring a return type as an unsigned long is meaningless given that it will be exposed as a normal JavaScript number (i.e. double-precision floating point value). It would be better to use a generic number type for those purposes, and create types that emphasize the potential coercion or validation strategies for use in those scenarios.

Finally, the spec is bloated with repetitive and spread-out text for performing the different numeric type coercions. The attributes [EnforceRange] and [Clamp] modifying the steps so that the types come to have drastically different behaviors when they are applied.

My proposed solution is to try to give tools that are both more aligned with spec-authoring use cases and clearer about what they are accomplishing. The complete functionality of the current types is preserved, and in fact further use cases (such as custom ranges) are enabled.

The proposal consists of removing all existing numeric types, as well as the [Clamp] and [EnforceRange] extended attributes, and replacing them with:

• A new number type, along with a [EnforceFinite] extended attribute that can apply to it, for documentation cases and for the most generic floating-point number processing.
• Two new parametrized types, IntEnforceWithin<x, y> and IntClampRound<x, y>, which are expected to be broadly useful for defining integer inputs that must stay within a specific range.
• Two new parametrized types, IntMod<x, y> and UintMod<y>, which are expected to be less useful and are mainly kept to enable matching legacy semantics.
• A to-be-determined set of typedefs to make the common cases that appear across specs more convenient.

Removal

We are trying to reform the following parts of WebIDL. So first, picture a universe without:

All existing numberic types

• byte
• octet
• short
• unsigned short
• long
• unsigned long
• long long
• unsigned long long
• float
• unrestricted float
• double
• unrestricted double

The numeric modifier extended attributes

• [EnforceRange]
• [Clamp]

Additions

Now let's get that funcitonality back, but better/faster/stronger.

number type and [EnforceFinite] extended attribute

The number type is the type that corresponds most closely to a JavaScript number. It is to be used:

• By all places that require no coercion, e.g. return types or constants
• For parameters, dictionary entries, etc. that do not need to enforce any particular behavior, but simply want to run ToNumber.

The [EnforceFinite] extended attribute is used to disallow NaN, +∞, or −∞.

The algorithm for converting an ES value v to a WebIDL number is:

1. Let n be ToNumber(v).
2. If the conversion to an IDL value is being performed in the presence of a [EnforceFinite] extended attribute, then
   1. If n is NaN, +∞, or −∞, throw a RangeError.
3. Return n.

This can express the following old patterns:

double              →  [EnforceFinite] number
unrestricted double →  number

TODO: where are the existing float and unrestricted float types used? How do we express those? What are their semantics anyway?

More-useful parametrized coercion types

Several new parametrized types are introduced specifically for use in places that require coercions (parameter lists, dictionary entries, setters). They are expected to be broadly useful. Unlike the previous types, they are not restricted to a predefined set of upper and lower limits. After all, it seems arbitrary to imagine that [-2147483648, 2147483647] is a more useful range than [0, 100] or [0, 360].

IntEnforceWithin<x, y>

Similar to today's [EnforceRange]. The algorithm for converting an ES value v to a WebIDL IntWithin<x, y> is:

1. Let n be ToNumber(v).
2. If n is NaN, +∞, or −∞, throw a RangeError.
3. Set n to sign(n) * floor(abs(n)).
4. If n < x or n > y, throw a RangeError.
5. Return n.

This can express the following old patterns:

[EnforceRange] byte               →  IntEnforceWithin<-128, 127>
[EnforceRange] octet              →  IntEnforceWithin<0, 255>
[EnforceRange] short              →  IntEnforceWithin<-32768, 32767>
[EnforceRange] unsigned short     →  IntEnforceWithin<0, 65535>
[EnforceRange] long               →  IntEnforceWithin<-2147483648, 2147483647>
[EnforceRange] unsigned long      →  IntEnforceWithin<0, 4294967296>
[EnforceRange] long long          →  IntEnforceWithin<-9007199254740991, 9007199254740991>
[EnforceRange] unsigned long long →  IntEnforceWithin<0, 9007199254740991>

IntClampRound<x, y>

Similar to today's [Clamp]. The algorithm for converting an ES value v to a WebIDL IntClamp<x, y> is:

1. Let n be ToNumber(v).
2. Set n to min(max(n, x), y).
3. Round n to the nearest integer, choosing the even integer if it lies halfway between two, and choosing +0 rather than −0.
4. Return n.

This can express the following old patterns:

[Clamp] byte               →  IntClampRound<-128, 127>
[Clamp] octet              →  IntClampRound<0, 255>
[Clamp] short              →  IntClampRound<-32768, 32767>
[Clamp] unsigned short     →  IntClampRound<0, 65535>
[Clamp] long               →  IntClampRound<-2147483648, 2147483647>
[Clamp] unsigned long      →  IntClampRound<0, 4294967296>
[Clamp] long long          →  IntClampRound<-9007199254740991, 9007199254740991>
[Clamp] unsigned long long →  IntClampRound<0, 9007199254740991>

Less-useful parametrized coercion types

Several parametrized coercion types are introduced simply to be able to maintain old semantics. They should probably not be used.

IntMod<x, y>

Used for emulating today's signed types. The algorithm for converting an ES value v to a WebIDL IntMod<x, y> is:

1. If n is NaN, +0, −0, +∞, or −∞, return +0.
2. Set n to sign(n) * floor(abs(n)).
3. Set n to n modulo x.
4. If n is ≥ y, set n to n - x.
5. Return n.

This can express the following old patterns:

byte      →  IntMod<256, 128>
short     →  IntMod<65536, 32768>
long      →  IntMod<4294967296, 2147483648>
long long →  IntMod<18446744073709552000, 9223372036854776000>

UintMod<x>

Used for emulating today's unsigned types. The algorithm for converting an ES value v to a WebIDL UintMod<x> is:

1. If n is NaN, +0, −0, +∞, or −∞, return +0.
2. Set n to sign(n) * floor(abs(n)).
3. Return n modulo x.

This can express the following old patterns:

octet              →  UintMod<256>
unsigned short     →  UintMod<32768>
unsigned long      →  UintMod<2147483648>
unsigned long long →  UintMod<9223372036854776000>

UintMod<360> might also be useful for any functions that want to process degrees.

Making these more convenient

Typedefs

We should do an audit to find what range coericons are commonly used on web specs, and define typedefs for them. My hope is that e.g. long long is used infrequently and mistakenly, so we wouldn't need a typedef of that sort; the spec could define its own, or use the awkward long name anyway. @bzbarsky says that at a cursory glance byte is unused. Etc.

We should almost certainly define a simple integer typedef. Unsure which is most idiomatic, but it should go up to 2⁵³ - 1. We would also likely want one for 0–255.

Names for these typedefs are undecided. They could use the existing names, although I am wary that these names give the mistaken impression of some correlation to a real type system.

Allowing power notation

Although again I hope that people aren't using the random-power-of-two ranges very often in their parameter coercions, if they are, we could allow e.g. UintMod<2^64> or UintMod<2**64> to replace UintMod<9223372036854776000>.

Shorter, less-precise names for the more-useful ones?

E.g. instead of IntEnforceWithin<x, y> we could do IntWithin<x, y> or even Int<x, y>. Instead of IntClampRound<x, y> we could do IntClamp<x, y>. Or we could get really cryptic with e.g. Int!<x, y> vs. Int_<x, y>.

Check if NodeFilter.length is defined correctly.

Seems to be 0 in Gecko/Chrome, not sure if the spec backs that.

Why don't default iterator prototypes chain up to `%IteratorPrototype%`?

Seems like that would be better than manually defining an @@iterator property on them. @heycam ?

DOMException function definition makes no sense

@domenic, how does http://heycam.github.io/webidl/#es-DOMException-call actually produce a DOMException instance? It's delegating to Construct() on its proto, which is %Error%, which certainly won't produce the right sort of object if the intent is to produce a "platform object". They need the right branding, etc.

Merge ES binding section into type definitions

Given that it's now been years since we killed off the Java binding side of things (and there can't be any other kind of binding but an ES binding for this spec), it's time to seriously consider merging together the type definitions with the binding instructions.

Having used this spec on a daily basis for years now, it's getting tiresome that I need to constantly jump from the type definition to the binding details by going through the TOC.

Stringifier says it requires DOMString, but should also allow USVString

The stringifier keyword MUST NOT be placed on an attribute unless it is declared to be of type DOMString.

URLUtils uses stringifier attribute USVString href.

Example code for [TreatNonObjectAsNull] is wrong

The following is the example code for [TreatNonObjectAsNull] given in http://heycam.github.io/webidl/#TreatNonObjectAsNull

WebIDL

[TreatNonObjectAsNull]
callback OccurrenceHandler = void (DOMString details);

callback ErrorHandler = void (DOMString details);

interface Manager {
  attribute OccurrenceHandler? handler1;
  attribute ErrorHandler? handler2;
};

ECMAScript

var manager = getManager();  // Get an instance of Manager.

manager.handler1 = function() { };
manager.handler1;            // Evaluates to the function.

try {
  manager.handler1 = 123;    // Throws a TypeError.
} catch (e) {
}

manager.handler2 = function() { };
manager.handler2;            // Evaluates to the function.

manager.handler2 = 123;
manager.handler2;            // Evaluates to null.

The example states that manager.handler1 = 123 will throw a TypeError, while manager.handler2 = 123 will not. However manager.handler1 has type OccurrenceHandler? where OccurenceHander is the callback interface that is marked as [TreatNonObjectAsNull]

All supported property names should be enumerable or none of them

Currently in the platform, the only interface with unenumerable property names is NamedNodeMap. In that interface, they are all unenumerable.

WebIDL should reflect that and forbid mixing unenumerable and enumerable property names.

Dead links to "consequential interface"

#dfn-consequential-interface is used in e.g. 4.3.18 [Unforgeable] but the anchor at the definition is #dfn-consequential-interfaces

Promise arguments should cast their results to a promise

It would be good if WebIDL automatically enforced Promise Arguments Should Be Cast, somehow.

Object.getPrototypeOf(NodeFilter) should be Function.prototype, not Object.prototype

http://heycam.github.io/webidl/#interface-object

The internal [[Prototype]] property of an interface object for a callback interface must be the Object.prototype object.

This doesn't match Edge and Gecko, where Object.getPrototypeOf(NodeFilter) === Function.prototype holds true. It looks like this could be fixed by using the same language as for non-callback interfaces that don't inherit from any other interface:

If the interface doesn't inherit from any other interface, the value of [[Prototype]] is %FunctionPrototype%

This was discussed in #83 and I just noticed it in whatwg/dom#186 (comment)

#78 is also more general issue about the interface objects of callback interface objects.

'Reject' definition.

In https://heycam.github.io/webidl/#named-properties-object-defineownproperty and https://heycam.github.io/webidl/#defineownproperty
The term "Reject" is referring to a non-existent section.
Ex:

...MUST behave as follows when called with object O and property name P. The term “Reject” is used as defined in section @@ @@.

1. Reject.

typo in the definition of an unrestricted double?

3.10.14 "The unrestricted double type is a floating point numeric type that corresponds to the set of all possible double-precision 32 bit IEEE 754 floating point numbers, finite and non-finite. [IEEE-754]"

Surely this should read "double-precision 64-bit floating point numbers", matching the normal double definition, right?

Missing extended attribute variant

Hi,

The HTML spec is using the following extended attribute a few times:

[Exposed=(Window,Worker)]
interface CanvasProxy { ... }

Examples:

• CanvasProxy
• CanvasRenderingContext2d

My reading of the IDL grammar doesn't seem to support this kind of list syntax.

Is this a bug in the HTML spec, a bug in WebIDL, or just me not reading the IDL grammar correctly?