Bug in lib.dom.d.ts - document.evaluate

[ststeiger]

In TypeScript (my version is 2.5), lib.dom.d.ts specifies document.evaluate as follows:
evaluate(expression: string, contextNode: Node, resolver: XPathNSResolver | null, type: number, result: XPathResult | null): XPathResult;

where

interface XPathNSResolver {
    lookupNamespaceURI(prefix: string): string;
}

So this means the following code

xmldoc.evaluate(
    '//ns1:RunLocatorResponse',
    xmldoc,
    function (prefix:string) : string {
        if (prefix === 'ns1')
            return 'http://tempuri.org/AWEService/API/WASAPI';
        else
            return null;
    },
    XPathResult.ANY_TYPE,
    null
);

reports function (prefix:string) : string cannot be assigned to XPathNSResolver.

However, as in the comments of this issue under note of DOM-Level-3-XPath-20040226 the DOM spec clearly says

Note: The parameter resolver of the method XPathEvaluator.evaluate is specified as an object that implements the XPathNSResolver interface. ECMAScript users can also pass to this method a function which returns a String and takes a String parameter instead of the resolver parameter.

So libdom.d.ts is missing an overload for
(prefix:string) => string
and that leads to a error-message for proper ECMAScript which is not transpiling, which is a bug.

[knrt10]

I would love to help in this, unfortunately I have no previous experience in the repository, would anyone please guide me?

[Fabianopb]

Hi @ststeiger, I was investigating this issue and I have a couple comments:

First, w3.org says "ECMAScript users can also pass to this method a function which returns a String and takes a String parameter instead of the resolver parameter."
Just for me to understand clearly, if this method is referring to evaluate then it seems you're right, we're missing the possibility of passing a function which returns a String and takes a String parameter in the lib.dom.d.ts type definitions, instead of the resolver with type XPathNSResolver, right?

Second, I noticed that your method either returns a string or null, which I think it shouldn't be possible in this case. If we're talking about a function which returns a String and takes a String parameter, then as you said the type should be (prefix: string) => string, but in reality your function's type is (prefix: string) => string | null. Does this make sense for you?

@RyanCavanaugh if you think we're good to go I have already scribbled a solution for this and could create a PR in no time!

Cheers!

[ststeiger]

To 1): I didn't write the spec, so why should I know ?
All I can say is that you can pass a function string=>string in all 3 major browsers, and it works as expected.

To 2): Since strings are nullable, null is a valid string value, so I don't see your problem, other than there being no typecast like return <string>null; But if you define null as its own type, then yes, it makes sense this way.

Also, the documentation for XPathNSResolver
https://www.w3.org/TR/2004/NOTE-DOM-Level-3-XPath-20040226/DOM3-XPath.html#xpath-XPathNSResolver
explicitly states:

Return Value: DOMString | Returns the associated namespace URI or null if none is found.

The spec only states that the prefix shouldn't be null.

[Fabianopb]

Buddy, no need to be harsh, this is an open discussion, I'm just trying to find a common understanding for all of us to get this right. Of course that it would be a good idea to confirm the information with the authors of the spec.

Sorry but "null is a valid string value" is fundamentally wrong, but of course that a method could return string | null if needed (but mind that they are different things).

Also, as I understand, the quote you pointed out is related to the return value of the lookupNamespaceURI. And if that's right, then this is something else that should be fixed because right now lookupNamespaceURI can only return string in the lib.dom.

So the fixes here would be (if our understanding of the spec is correct):

• lookupNamespaceURI should also return null
• evaluate's resolve should also accept a method that takes a string and returns a string or null

Let's wait for @RyanCavanaugh's opinion on that.

[ststeiger]

It wasn't meant harsh, but sorry anyway.
Hm, that's an interesting concept - type changes to object if string is set to null, so string as such is indeed non-nullable.

Yes, the return value is that of lookupNamespaceURI.
In that case, lookupNamespaceURI should also be fixed, yes.

[RyanCavanaugh]

Sounds like you guys are on the right track.

Strings are only nullable by default when strictNullChecks is off, so having the return type be string | null if null is actually a meaningful return value is important.

[Fabianopb]

Thanks for the input @RyanCavanaugh and @ststeiger! I'll submit a PR and then we can discuss upon that, how does it sound?