Web IDL: Defining Web APIs and Implementing JavaScript Bindings

…there was the DOM.

• Access to HTML, XML and other tree-based markup languages.
• DOM Level 1 was published in 1998.
• First use of OMG IDL to describe interfaces that DOM objects implement.

        interface Node {
          const unsigned short ELEMENT_NODE   = 1;
          const unsigned short ATTRIBUTE_NODE = 2;
          ...
          readonly attribute DOMString nodeName;
                   attribute DOMString nodeValue;
          ...
          Node appendChild(in Node newChild) raises(DOMException);
          ...
        };
      

        interface Node {
          const unsigned short ELEMENT_NODE   = 1;
          const unsigned short ATTRIBUTE_NODE = 2;
          ...
          readonly attribute DOMString nodeName;
                   attribute DOMString nodeValue;
          ...
          Node appendChild(in Node newChild) raises(DOMException);
          ...
        };
      

        interface Node {
          const unsigned short ELEMENT_NODE   = 1;  // constants
          const unsigned short ATTRIBUTE_NODE = 2;
          ...
          readonly attribute DOMString nodeName;
                   attribute DOMString nodeValue;
          ...
          Node appendChild(in Node newChild) raises(DOMException);
          ...
        };
      

        interface Node {
          const unsigned short ELEMENT_NODE   = 1;
          const unsigned short ATTRIBUTE_NODE = 2;
          ...
          readonly attribute DOMString nodeName;  // attributes
                   attribute DOMString nodeValue;
          ...
          Node appendChild(in Node newChild) raises(DOMException);
          ...
        };
      

        interface Node {
          const unsigned short ELEMENT_NODE   = 1;
          const unsigned short ATTRIBUTE_NODE = 2;
          ...
          readonly attribute DOMString nodeName;
                   attribute DOMString nodeValue;
          ...
          Node appendChild(in Node newChild) raises(DOMException);
          ...  // operations
        };
      

Defines a set of C-like types — float, bool, unsigned long, …

• DOM designed with two target languages in mind: Java and JS.
• OMG defines IDL bindings for various specific languages…
  …but not for JavaScript!
• So DOM has language binding appendices for Java and JavaScript.
  (DOM Levels 1, 2 and 3 target ECMAScript 3rd Edition, although the 5th Edition is current.)

• The JS language binding appendix is not very precise.
• Precision — and accuracy — is required for interoperability!

• JS has a few types:
  • Undefined – undefined
  • Boolean – false, true
  • Number – 0, -2.5, Infinity, NaN
  • String – "", "hello"
  • Object – { }, { "key": "value" }, [1, 2, 3], function() { }, /^regexp?$/

• JS objects have properties, each with a String name and either a value (data property) or a getter/setter pair (accessor property).
• Properties have attributes: Writable, Enumerable, Configurable
• JS objects can also have a prototype object for simple inheritance:
  array_instance → Array.prototype → Object.prototype → null
  • array_instance = [10, 20, 30]: 0, 1, 2, length
  • Array.prototype: push, pop, concat, …
  • Object.prototype: toString, …

• Both ECMAScript 3rd Ed. and 5th Ed. have neither classes nor constants. What JS constructs do IDL constants correspond to? Non-writable data properties?
• Shouldn’t the ELEMENT_NODE property be on both Node and Node.prototype?

• What does it mean for a property to have a type?
• What if we assign something other than a String?

            anElement.nodeValue = 0x10;
            anElement.nodeValue = ({ "toString": function() { return "a"; } });
          

• Is it a data property or an accessor property? Observable with Object.getOwnPropertyDescriptor().

• Does the property live on a Node instance or its prototype?
• Can you pass ({ "nodeType": Node.ELEMENT_NODE }) to it?
• What about: nodesubclass_instance → NodeSubclass → Node → Object

            function NodeSubclass() { }
            NodeSubclass.prototype.__proto__ = Node.prototype;
            document.documentElement.appendChild(new NodeSubclass());
          

• All these questions (and many more) are unanswered by the original DOM specification.
• All Web specifications up until 2008 were written like this.
• Ten years’ worth of unspecified behaviour!
• But we should be able to answer these questions consistently for all specifications at once.

• http://www.w3.org/TR/WebIDL/
• Originally named “Language Bindings for DOM Specifications”.
• Two goals:
  1. Resolve unspecified behaviour from the use of OMG IDL.
  2. Allow more JavaScript-appropriate APIs to be defined, while still supporting language independence.

• Type mappings:  IDL unsigned short ↔ JS Number
• Type conversions:

              anElement.nodeValue = 0x10;
              anElement.nodeValue = ({ "toString": function() { return "a"; } });
            

  Any JS value is converted to an IDL DOMString value by effectively passing it to the global String() function.

              anElement.nodeValue = "16";
              anElement.nodeValue = "a";
            

• Type conversions:

              var nodeLike = ({ "nodeType": Node.ELEMENT_NODE });
              document.documentElement.appendChild(nodeLike)
               
              function NodeSubclass() { }
              NodeSubclass.prototype.__proto__ = Node.prototype;
              document.documentElement.appendChild(new NodeSubclass());
            

  Author created JS objects will never be considered to implement an interface such as Node. A TypeError exception will be thrown.

• Properties:
  • Constants: non-writable, non-configurable, enumerable data property, on both Node and Node.prototype.
  • Attributes: configurable, enumerable accessor property on the prototype.
  • Operations: configurable, enumerable data property (with a Function value) on the prototype.
• Not magical, helps author understanding, allows monkeypatching.

• Many other things:
  • What happens when you pass too many/few arguments.
  • What happens when you grab a Function corresponding to an IDL operation and apply it to some other type of object.
  • How interface inheritance corresponds to a prototype chain.
  • How DOM objects are stringified.
  • …

• The base OMG IDL language is extended to support defining behaviours that JS supports.
• API ergonomics tailored to JS first.

• The NodeList interface exposes array-like properties:

              var kids = document.documentElement.childNodes;
              alert(kids);  // [object NodeList]
              alert(kids[0]);  // [object HTMLHeadElement]
              alert(kids[1]);  // [object HTMLBodyElement]
            

• Keywords to implement these indexed properties:

              interface NodeList {
                getter Node? item(unsigned long index);
                readonly attribute unsigned long length;
              };
            

• The [Constructor] extended attribute declares that you can use new on the interface:

              [Constructor]
              interface Document : Node {
                readonly attribute Element? documentElement;
                ...
              };
            

  Then:

              var doc = new Document();
            

• Dictionary types are used for named-argument objects:

              [Constructor(DOMString type, optional EventInit eventInitDict)]
              interface Event {
                void initEvent(DOMString type, boolean bubbles, boolean cancelable);
                ...
              };
              dictionary EventInit {
                boolean bubbles;
                boolean cancelable;
              };
            

• Instead of:

              var event = document.createEvent("Event");
              event.initEvent("click", true, false);
            

  you can write:

              var event1 = new Event("click", { bubbles: true, cancelable: false });
              var event2 = new Event("click", { bubbles: true });
              var event3 = new Event("click");
            

• String constant enumerations:

              enum CanvasDrawingStylesFillRules { "nonzero", "evenodd" };
              interface CanvasRenderingContext2D {
                attribute CanvasDrawingStylesFillRules fillRule;
                ...
              };
            

  Then:

              var ctx = document.querySelector("canvas").getContext("2d");
              ctx.fillRule = "evenodd";
              ctx.fillRule = "something";  // throws TypeError
            

1. Can copy/paste IDL directly from specifications.
2. Easier to write C++ classes implementing interfaces.
3. Generated code is simpler and faster.

• 100× faster than standard old bindings (plain XPConnect).
• 4–5× faster than quickstubbed old bindings (use of properties with JS Functions that know what IDL member they correspond to and what type of object they're on).
• 2.5–3× faster than custom quickstubs (additional hand written C++ to perform argument type conversion and dispatch).
• Fast behaviour by default.
• On a 2.7 GHz machine: ~1 us → 8–9 ns.

Cameron McCormack, Mozilla · @heycam