Support older minor releases of the TypeScript compiler

[octogonz]

Repro

Create a TypeScript file that imports the @typescript-eslint library like this:

index.ts

import { TSESLint } from '@typescript-eslint/experimental-utils';

Expected Result

The code compiles without errors using an older compiler (TypeScript 3.5 in our case).

Actual Result

Compilers older than TypeScript 3.7 fail to build:

error TS2307: Cannot find module '@typescript-eslint/experimental-utils'.

The reason is that the excerpt below is using a newer language feature that is not supported by older compilers:

@typescript-eslint/experimental-utils/dist/index.d.ts

export * from './AST';
export * from './CLIEngine';
. . .

Additional Info

It would be nice for projects to always use the latest TypeScript compiler version. However, in large production code bases, upgrading the compiler can involve a lot of work. For example, maybe there are custom plugins or tools that need to be updated to work with the latest compiler engine. Or the upgrades may be blocked behind the release of a customer SDK that targets a specific TypeScript version.

The TypeScript group does not guarantee that .d.ts files will be backwards compatible for a previous minor version. (The 3.7 release famously broke backwards compatibility even for source code that avoids using any new language features.)

The recommendation is for libraries to use the downlevel-dts tool to rewrite the .d.ts outputs to be backwards compatible with earlier compiler releases.

Versions

package	version
@typescript-eslint/experimental-utils	3.3.0
TypeScript	3.5.3
node	12.17.0
npm	6.14.4

[bradzacher]

We actually do now use downlevel-dts as of 3.1.0 (#2133) after I broke <3.8 by using private class members.

You can see the downlevelled TS files in the _ts3.4 folder in our package:
https://unpkg.com/browse/@typescript-eslint/experimental-utils@3.3.0/_ts3.4/dist/index.d.ts

I also had a play, and export * from 'foo' has been supported in typescript for many versions. You might be confusing it with export * as foo from 'foo', which was only added in 3.8.

I'm not sure why it's not working. Do I have the configuration incorrect?

[octogonz]

I also had a play, and export * from 'foo' has been supported in typescript for many versions.

If this was true, then I wonder why downlevel-dts rewrites it in _ts3.4/dist/index.d.ts.

We actually do now use downlevel-dts as of 3.1.0 (#2133) after I broke <3.8 by using private class members.

That's interesting, because upgrading to TypeScript 3.9 definitely made the error go away. Lemme investigate a little more.

[bradzacher]

If this was true, then I wonder why downlevel-dts rewrites it

It doesn't, this is actually 1:1 our index.ts file:

typescript-eslint/packages/experimental-utils/src/index.ts

Lines 1 to 8 in 906c822

	import * as ASTUtils from './ast-utils';
	import * as ESLintUtils from './eslint-utils';
	import * as JSONSchema from './json-schema';
	import * as TSESLint from './ts-eslint';
	import * as TSESLintScope from './ts-eslint-scope';
	export { ASTUtils, ESLintUtils, JSONSchema, TSESLint, TSESLintScope };
	export * from './ts-estree';

upgrading to TypeScript 3.9 definitely made the error go away

Yeah in testing it looks like any version < 3.8 breaks. It looks like typescript is at the very least understanding the typesVersions declaration we have, but it's not resolving correctly.

typescript-eslint/packages/experimental-utils/package.json

Lines 57 to 63 in 906c822

	"typesVersions": {
	"<3.8": {
	"*": [
	"ts3.4/*"
	]
	}
	}

[octogonz]

Here's an isolated repro: https://github.com/octogonz/typescript-eslint-repro

[bradzacher]

dammit, I know what it is.

In that PR I originally was going to call the folder ts3.4, but then I changed it to _ts3.4 so that it was sorted to the top in the folder tree.

During testing by locally linking, I must not have nuked the old ts3.4 folder, which is why it "worked" when it shouldn't have.

Fixing that line makes it work fine.

[bradzacher]

This will be released to the canary tag in a few minutes

[octogonz]

Awesome, thanks for the quick fix!