Question on undocumented API

[hriss95]

• Version: v4.2.6
• Platform: 4.4.0-34-generic [streams] _flush not being called #53-Ubuntu SMP Wed Jul 27 16:06:39 UTC 2016 x86_64 x86_64 x86_64 GNU/Linux
• Subsystem:

Hello, I am trying to help with keeping node.d.ts up to date in DefinitelyTyped (Using node's API in TypeScript).

There was a recent discussion on what part of the API exactly should be documented as only what is intended for public use is the current logic behind DefinitelyTyped's way of introducing definitions. That said, I've encountered on numerous occasions that there are functions that are available to me(for example could be seen by running node and display the exports object for a given module using require() ) and are not present in the documentation or at least not in the current one. There were 2 recent cases on DefinitelyTyped. One was involving "querystring" and its unescapeBuffer function which could be seen after running require("querystring") - there is no documentation for it, but it could still be used in no different way than the others. The other case was concerning the "vm" module and it's createScript function which actually has documentation but in older versions of node like this.

So, my question is whether these 2 (and any other similar cases that might be found) are meant for public use. Currently, due to the nature of TypeScript and the fact that they are not present in the documentation, these 2 functions mentioned cannot be used by TypeScript users that rely on DefinitelyTyped's definitions for node. Since DefinitelyTyped is the repository which most of the users get their definitions from I created a pull request there adding these and got an answer that I should create an issue here on whether these are public or not. Thank you in advance for the help!

[mscdex]

IMHO anything that's undocumented (and accessible) is "use at your own risk." It could go away or change at any time and is not supported.

[hriss95]

That seems reasonable. However, the question was more about the fact that TypeScript can allow or disallow the usage of such functions simply by including/excluding them from the definition file for node. So, I guess, the question is whether TypeScript users who want to use node should be allowed to use them or not(since TypeScript can actually enforce that)

[mscdex]

I don't think this is something that should be decided by node core, but rather by the TypeScript folks and/or their end users.

[cjihrig]

Just my personal opinion, but if you can prevent your users from accessing undocumented APIs, it will probably save them headaches somewhere down the line. They mostly only exist because in the past, core didn't have a way to make things internal only.

Either way, I'm going to close this, as there is nothing for us to do here. Feel free to keep the discussion going.

[hriss95]

Thank you for the response. I guess it does sound reasonable that you should probably not be able to use undocumented stuff that can be changed or removed.

[ChALkeR]

Perhaps we should deprecate or document unescapeBuffer?

[watilde]

I also just came up with the same things for qs. unescapeBuffer and qs.decode. I think it's better to mention them in the docs as use at your own risk if it's so.

[sam-github]

We can document them as doc-only deprecated, then start the deprecation train (hard deprecation, removal into internal where they cannot be used by users).

[joyeecheung]

I think somewhere @mscdex mentioned starting to document qs.unescapeBuffer would be better because it is actually useful?