Node-slack-sdk: 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 [ ])

• [x] I've read and understood the Contributing guidelines and have done my best effort to follow them.
• [x] I've read and agree to the Code of Conduct.
• [x] 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 https://github.com/Microsoft/TypeScript/pull/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... 🤔

[aoberoi]

i think this means we cannot adopt this syntax until we officially do not support typescript <3.0. my gut feeling is that its way too soon to drop version support so soon. but this is the first time there's been a major version transition in typescript since this project became written in typescript, so i admit we've got some learning ahead of us to understand how to do this transition smoothly.

[aoberoi]

for now the workaround is still to add esnext.asynciterable to the lib compiler option.

[aoberoi]

after consulting a few colleagues who have more typescript experience than me, its clear that the resolution to this issue is better documentation.

in short, we'd love to use all the new hotness in TypeScript 3.0+, but it would be too soon to force that upon all users of this package. i'm going to create a separate issue to contain discussion around how and when exactly we can make TypeScript 3.0+ (or any version really) a requirement for this package. we can implement the triple-slash directive based solution at that time.