Document correspondence between TypeScript and tslib versions

[calebegg]

Tagged tslib versions don't seem to correspond in any obvious way to TypeScript versions. I want to be able to confidently import the right tslib version to work with a given TS version. Maybe just a table in the readme would be enough?

[mhegazy]

support of importHelpers was added in TS 2.1. you should be able to use any version of tslib with any version of TS post TS 2.1. Obviously the behavior you get from the helpers depends on what version of the library you are using.

Is there a specific issue you found with different versions of the library and/or TS?

[calebegg]

v1.0.0 doesn't have __generator, so it won't work with 2.1's async/await support. And v1.5.0 has a version of __extends that uses Object.setPrototypeOf, which is a change slated for TS 2.2; I don't want to introduce new breaking changes to our large TS 2.1 codebase.

I just happened to notice those. There might have been other changes in the other versions. I want to just be able to exactly match the behavior of TS 2.1 without noEmitHelpers.

[aluanhaddad]

@calebegg the use of Object.setPrototypeOf is guarded, making it non-breaking from an environmental perspective.

[calebegg]

I didn't mean to say that that change was a breaking one, but that there might be other breaking changes. And with our large codebase, even innocent seeming changes like that can cause issues for anyone depending on the old behavior.

I just want to be able to get a version that works just like TS does on its own without having to research each change to know when it went in.

[aluanhaddad]

@calebegg Fair enough. I support this request.

[frankwallis]

There is some info in the release notes (https://github.com/Microsoft/tslib/releases)

NOTE: This is a breaking change from TypeScript 2.3.2 and earlier when using tslib with async generators:

If you are using TypeScript 2.3.2 or earlier and are writing async generators, you must use tslib version 1.6.1.
If you are using TypeScript 2.3.3 or later and are writing async generators, you must use tslib version 1.7.0 or later.

But I agree it could be more explicit, perhaps tslib should be an optional peer dependency of typescript? https://github.com/npm/npm/issues/3066

[aluanhaddad]

@frankwallis the peer dependency possibility occurred to me also but I think it may cause more problems than it solves because it rules out multi versioning. Packages depending on different versions of TSlib should be a well supported scenario.

[octogonz]

The compatibility between tslib and typescript library versions should be documented at least.

Ideally there should be a way to validate it. We allow people to build bundles using different typescript compilers (sometimes ancient compiler versions, to target compatibility with old product releases). When these bundles are loaded, they can be dynamically linked to the same tslib library. (For example, we might have 30 bundles on our page, so we wouldn't want to load 30 copies of tslib.) If an incompatibility caused a bundle to fail, we wouldn't find out until runtime when someone did something to load that component. If needed, we could dynamically link a bundle to an older tslib to ensure compatibility -- but only if this mapping was actually documented somewhere.

@nickpape-msft

[orta]

Coming in late, today we describe the versions of tslib according to their TypeScript versions:

# TypeScript 3.9.2 or later
npm install tslib

# TypeScript 3.8.4 or earlier
npm install tslib@^1

# TypeScript 2.3.2 or earlier
npm install [email protected]

Is that enough? Or is the answer a table somewhere saying the version which correlated to a release?

[octogonz]

Is that enough?

Technically. 👍

Or is the answer a table somewhere saying the version which correlated to a release?

To a casual observer, those three version mappings are so higgledy-piggledy as to raise a quiet doubt whether they are the whole story. Gussying it up with a nice-looking table might help. :-)

[agilgur5]

Ran into this from https://github.com/formium/tsdx/pull/719#issuecomment-683470971 where I could only tell from the Release Notes that tslib@2 was only compatible with TS 3.9+ as there is no peerDep listed. In https://github.com/formium/tsdx/pull/904#issuecomment-708283064 I also pointed out that the lack of peerDep also makes it difficult to tell on install/automated dep upgrades whether or not one is compatible, as no peerDep error is printed out.

Is there a way to specify this in a way that is more automated or are we limited to a way that is more manual/user/docs-driven due to https://github.com/microsoft/tslib/issues/22#issuecomment-318492123 ?