Document compatibility of tslib with typescript

[dzearing]

We are seeing numerous packages which depend on tslib 1.x and 2.x. We'd like to de-duplicate these, but there doesn't seem to be clear docs on if it's safe to update to the latest tslib 2.x when using older TypeScript versions to build. Some folks internally have mentioned that if you're on TS < 3.9, use 1.x. Else it's ok to use 2.x. I'd like to confirm if that's the case.

If there are specific TypeScript minbar versions before we ask everyone to update to 2.x, it would be great to list them in the README so that people can be aware, and also so that we can communicate the dependency. We wouldn't want to ask someone to upgrade, if it's not compatible with the TypeScript version they're using.

[ecraig12345]

Adding on, it would be great to have a table in the docs along these lines (with the ??? replaced with actual answers of course):

Library compiled with	Library consumed with	tslib 1 supported?	tslib 2 supported?
< 3.9	< 3.9	yes	???
< 3.9	>= 3.9	yes?	???
>= 3.9	>= 3.9	???	yes
>= 3.9	< 3.9	???	???
>= 3.9	>= 3.9	no	yes

[DanielRosenwasser]

Thanks for building out that table - let's try to work through this on this issue. Maybe @rbuckton and @weswigham can help me reason through this.

---

So I've forgotten the nuances of why __createBinding changes forced us to bump to 2.0. You can get a gist of it from

#103
#109
#112

@weswigham has a specific comment #103 (comment)

This is only an issue when using tslib with old emit, right? The emit TS 3.9 has hoisted exported variable assignments such that the __exportStar helper won't override local export names, and such that they can be reconfigured later on once actually assigned.

So basically, it sounds like any library that consumes tslib 2 cannot work with < 3.9. If that's correct, we can fill in the top right of the table.

Library compiled with	Library consumed with	tslib 1 supported?	tslib 2 supported?
< 3.9	< 3.9	yes	no!
< 3.9	>= 3.9	yes?	no!
>= 3.9	>= 3.9	???	yes
>= 3.9	< 3.9	???	???
>= 3.9	>= 3.9	no	yes

For something created in 3.9+, I think you would have a behavior where consumers can actually read values, but they fall into some confusing behavior once they try to re-export conflicting values. That might give you a "yes-ish". You basically get the same issues as if you did CommonJS interop with any other library if I've understood correctly.

Library compiled with	Library consumed with	tslib 1 supported?	tslib 2 supported?
< 3.9	< 3.9	yes	no!
< 3.9	>= 3.9	yes?	no!
>= 3.9	>= 3.9	???	yes
>= 3.9	< 3.9	yes-ish!	yes-ish!
>= 3.9	>= 3.9	no	yes

Finally, if you try to use TS 3.9+ with tslib 1.x, it may be lacking helper functions. So it sounds like those just won't work.

Library compiled with	Library consumed with	tslib 1 supported?	tslib 2 supported?
< 3.9	< 3.9	yes	no!
< 3.9	>= 3.9	yes?	no!
>= 3.9	>= 3.9	no!	yes
>= 3.9	< 3.9	yes-ish!	yes-ish!
>= 3.9	>= 3.9	no	yes

Hopefully my team can help correct me.

[eddiemonge]

This is a duplicate of #22 it seems