Thread: Definition files and the law! There are competing theories on how to interpret laws. Some say you should only read the literal text of it; others say you have to examine the intent of the authors. Many nuanced takes exist.
Definition files have a similar problem. Are we meant to describe the documented surface area of the library? The intent of the library as written? The actual runtime behavior if called? These are all different!
For example, is parseInt([4]) returning 4 an "intended" use of the function? That's what it does, but if this were an npm package, the author changing that behavior (e.g. to throw) might not consider it a semver break.
Most of the time, the correct thing is for a definition file to describe the intent of the library when used correctly. This can be hard because documentation is often *extremely* vague; e.g. "this takes an 'object'" is ~useless.
As a library author, if you just step back 100% from the authorship of the definition file, what you're really saying is that you don't know how (or care to describe) your own library is intended to be used. That's your choice, but it is kinda weird.
Maintainers on DefinitelyTyped are often left trying to read tea leaves from unclear documentation, observed runtime behavior, or other clues.
I'm not saying you should own your lib's definition file if you don't want to or aren't willing to put in the effort - that is a bigger mistake. But if people are arguing on your issue tracker about it, consider what it means:
People today argue about commas and exclusive vs inclusive 'or's in the Constitution because the intent of the authors was unclear and the authors are dead. People arguing about the correct use of your library can't figure out your intent!
It means that people trying to write down a formal description of how your code is intended to be used *can't figure it out*. That's a problem for everyone, not just TypeScript users. The TS users are just discovering it first.
It means later on, you're going to make an innocuous change in a codepath you think is outside the currently-documented surface area, and end up breaking people who didn't know this was what your intent was.
To summarize: People trying to write definition files are the canary in the coal mine for whether or not you've sufficiently documented the intended use cases of your library.
