NodeList, NodeListOf<Element> and HTMLCollection

[FranklinWhale]

Currently, the following DOM methods has a return type definition of NodeList, but the type of nodes returned is actually always Element:

getElementsByClassName
getElementsByTagNameNS
getElementsByTagName(name: string)
getElementsByName
msElementsFromPoint
msElementsFromRect

As a result, a cast to Element is required before any method of Element can be used. To remove the need of the cast, I suggest changing their return type definition to NodeListOf<Element>.

Also, there are some HTML DOM properties (e.g. document.forms) having a return type definition of HTMLCollection, but HTMLCollection does not extend NodeListOf<HTMLElement>. That leads to some difficulties in creating a method that takes a list of elements. I suggest changing HTMLCollection to extend NodeListOf<HTMLElement>.

Finally, should a List<T> interface with the following definition be created, such that Array<T>, NodeList, NodeListOf<HTMLElement> and HTMLCollection all extend to List<T>?

interface List {
    length: number;
    [index: number]: T;
}

[RyanCavanaugh]

Good feedback. We'll need to look at this again when we rewrite the lib.d.ts generator.

[taylorhutchison]

Still being burned by this issue. getElementsByTagName (and other DOM Element selectors) seem to have a long-running history (documented here: https://bugzilla.mozilla.org/show_bug.cgi?id=14869) of returning HTMLCollection instead of NodeList.

[duanyao]

In many cases, we want certain sub-interface of Element to be returned from those DOM APIs.

Firstly, I suggest making those API as generic methods, e.g.:

interface NodeSelector {
  querySelector<E extends Element>(sel : string): E;
  querySelectorAll<E extends Element>(sel : string): NodeListOf<E>;
  //...
}

Additionally, I suggest making the non-generic versions return a UniversalElement or a list of it. UniversalElement is an imaginary Element that extends all known sub-interfaces of Element. Say:

interface UniversalElement extends
  HTMLAElement,
  HTMLInputElement,
  //...
  SVGLineElement,
  SVGRectElement,
  //...
 {}

interface NodeSelector {
  //...
  querySelector(sel : string): UniversalElement;
  querySelectorAll(sel : string): NodeListOf<UniversalElement>;
}

Rationales:

• UniversalElement makes most type assertions unnecessary in DOM related codes, so that greatly simplifies those codes.
• APIs like querySelector can actually return any sub type of Element, depending on the parameter and context, so it is not that crazy to let them return UniversalElement by default.
• This change won't break existing (correct) codes.
• Maybe UniversalElement makes it easier for developers to produce type errors in rare cases (I haven't figured out one however), but they can use the generic version of those APIs to narrow down the return type if necessary.

However, there is a member conflicting problem: SVGElement has a few conflicting members with HTMLElement. For example className in HTMLElement is a string, but in SVGElement is a SVGAnimatedString.

One possible solution is also making className unified:

interface UniversalClassName extends String, SVGAnimatedString {}

interface UniversalElement {
  className: UniversalClassName;
}

However, because primitive types in TS are not interfaces, and an instance of interface String can't be used as a string directly, so you can't pass UniversalClassName to a context where string is expected; a cast or conversion is needed. Still wondering how to workaround this limitation. Is this a TS bug?This seems can't be easily workarounded (see http://typescript.codeplex.com/discussions/459084). So this solution has too high a price to pay.

Another solution is kicking out SVG's funny className and other incompatible properties from UniversalElement. After all, we use HTMLElement most of the time. We may create a PartialUniversalSVGElement interface which gathers all SVG elements' members except incompatible ones, and let UniversalElement extend it.

[mhegazy]

PRs welcomed, here is some information about submitting lib.d.ts changes: https://github.com/Microsoft/TypeScript/blob/master/CONTRIBUTING.md#contributing-libdts-fixes

[crash-dive]

I am happy to add this. But I need to know what would be accepted. I was thinking of adding a new type modelled on NodeListOf called HTMLCollectionOf and then adding generic methods for the collection methods. For example I have these in the project I have open at the moment:

interface Document
{
    getElementById<THTMLElement extends HTMLElement>(elementId: string): THTMLElement;
    getElementsByClassName<THTMLElement extends HTMLElement>(classNames: string): NodeListOf<THTMLElement>;
}

interface Element
{
    getElementsByClassName<THTMLElement extends HTMLElement>(classNames: string): NodeListOf<THTMLElement>;
}

interface NodeSelector {
    querySelector<THTMLElement extends HTMLElement>(selectors: string): THTMLElement;
    querySelectorAll<THTMLElement extends HTMLElement>(selectors: string): NodeListOf<THTMLElement>;
}

Not an exhaustive list but just an example I have to hand.

Thoughts?

[mhegazy]

@crash-dive this looks like can be handled in a separate PR. the OP was about 1. adding a new HTMLCollectionOf<T extends HTMLElement> extends HTMLCollection and wiring this in the correct placeds. 2. switch msElementsFromRect and msElementsFromPoint to return NodeListOf<Element>, and possibly others that match their style. and 3. make NodeList, NodeListOf, HTMLElementCollection, HTMLElementCollectionOf to extend from ArrayLike