[darepublic]

the type definition of the same is clearer imo and not only that it is enforced by both the ide and the compiler. Libraries typically DO NOT write a bunch of code examples of all the legitimate arguments that can be passed. Also in your example above,

> .addClass(function(node, i) {return 'name1'})

^ what is node? What is i? Seems intuitive to think it must be a dom reference and an index. But in different domains it's not always gonna be so clear. Like I am not familiar with umbrella js, but maybe node could be a jquery object and not a plain dom ref? With typescript you can just say

type GetClassName = (node: HTMLElement, i: index) => string | string[]

// see how I added string[]. So I don't have to add yet another example

// of a function returning a string array instead of a string

and then add it to the union of types that can be passed into addClass. Great, no more guessing based on the domain knowledge I have (or don't), it's crystal clear. And it forces the lib developer to have the discipline to make it crystal clear, which they usually don't I'm afraid.