Document lib dependencies in TypeScript compiler options

[aoberoi]

Description

It has been pointed out (in #612) that it isn't completely clear which TypeScript lib compiler option requirements your application must have when using this library.

While the default compiler options with assign lib to either DOM,ES5,ScriptHost or DOM,ES6,DOM.Iterable,ScriptHost (depending on the target JS version), this library using AsyncIterable<T>, which means it also requires esnext.asynciterable.

What is the right way for typescript libraries to declare this sort of dependency?

Requirements (place an x in each of the [ ])

• I've read and understood the Contributing guidelines and have done my best effort to follow them.
• I've read and agree to the Code of Conduct.
• I've searched for any related issues and avoided creating a duplicate issue.

[aoberoi]

note: it looks like in typescript 3.1, esnext.asynciterable will actually become es2018.asynciterable (and included in just es2018) - see microsoft/TypeScript#26220.

[freezy]

Can't you just reference the lib in util.d.ts?

[aoberoi]

i wasn't aware of the technique for declaring a lib dependency the way you mentioned in #612. from reading the documentation on this feature, it seems reasonable to me. just to be safe, if you have any other examples of libraries that use this technique to declare their own lib requirements, would you be able to link me to them?

[freezy]

Off the top of my head, no. But from the doc:

Built-in lib files are referenced in the same fashion as the "lib" compiler option in tsconfig.json (e.g. use lib="es2015" and not lib="lib.es2015.d.ts", etc.).

So if you previously only had it in your tsconfig.json, moving it to the file directly should have the same effect.

[aoberoi]

okay, sounds reasonable to me. thanks for helping improve our (my) understanding of TypeScript 💯!

[aoberoi]

@freezy i've created the PR for this, and i realized there's a risk with this change. if when typescript 3.1 is released, this lib is no longer named esnext.asynciterable and instead named es2018.asynciterable, then how can this library declare a reference that works across both old versions of typescript and new?

for now, i think merging this is still better than not. but i'd like to leave this issue open until we figure out the solution for this upcoming problem.

[aoberoi]

hmm its not as simple as adding the line to util.ts. it seems like the tsc is responsible for emitting triple slash directives into the resulting declarations file (util.d.ts). for example, without the above PR, util.d.ts starts with:

/// <reference types="node" />

of course, we could post-process util.d.ts to add the lib reference, but that feels like the wrong way to do this. i'm searching the web for more information about this.

[aoberoi]

oh i think that syntax is first introduced in typescript 3.0... 🤔