Add --preserveValueImports

[andrewbranch]

Fixes #43393
Successor of #44137

Adds a flag --noErasingImportedNames which prevents the elision of unreferenced value-having imports in JS:

// index.ts
import { readFile } from "fs";
eval("console.log(readFile)");

// tsc --module=es2015 💥
eval("console.log(readFile)");
export {};

// tsc --module=es2015 --importsNotUsedAsValues=preserve 💥
import "fs";
eval("console.log(readFile)");

// tsc --module=es2015 --noErasingImportedNames ✅
import { readFile } from "fs";
eval("console.log(readFile)");

It does not prevent the elision of imports that resolve to types or type-only exports, because that would create runtime errors:

// mod.ts
export interface I {}
class C {}
export type { C };

// index.ts
import { I, C } from "./mod";

// tsc --module=es2015
export {};

// tsc --module=es2015 --importsNotUsedAsValues=preserve
import "./mod";

// tsc --module=es2015 --noErasingImportedNames
export {};

However, this means that when combining --noErasingImportedNames with --isolatedModules, types and type-only exports must be imported with import type. Otherwise, single-file transpilation can’t know what import specifiers are safe to preserve:

import { writeFile, WriteFileOptions } from "fs";
//                  ^^^^^^^^^^^^^^^^
// TS1444: 'WriteFileOptions' is a type and must be imported with a type-only import when 'noErasingImportedNames' and 'isolatedModules' are both enabled.

To make this restriction easier to deal with, a subsequent PR will enable making individual import specifiers type-only:

import { writeFile, type WriteFileOptions } from "fs"; // ✅

That PR will also adjust auto-import and organize imports behavior according to these options.

The flag is only valid in es2015+ module emit because downleveling ESM imports to other module systems involves creating a temporary variable with a mangled name and doing property access off that name, so preserving names as written is not possible—the eval example wouldn’t work because the way to access readFile in the JS would be fs_1.readFile (or another subscript if conflicting), not readFile.

[andrewbranch]

@typescript-bot pack this

[typescript-bot]

Heya @andrewbranch, I've started to run the tarball bundle task on this PR at 0b02873. You can monitor the build here.

[andrewbranch]

@typescript-bot pack this

[typescript-bot]

Heya @andrewbranch, I've started to run the tarball bundle task on this PR at bc91a25. You can monitor the build here.

[typescript-bot]

Hey @andrewbranch, I've packed this into an installable tgz. You can install it for testing by referencing it in your package.json like so:

{
    "devDependencies": {
        "typescript": "https://typescript.visualstudio.com/cf7ac146-d525-443c-b23c-0d58337efebc/_apis/build/builds/108911/artifacts?artifactName=tgz&fileId=4C756A27CDE9FBA8D08572FA701057DC38B850454CF058150C36EFD3FA07C3BD02&fileName=/typescript-4.5.0-insiders.20210819.tgz"
    }
}

and then running npm install.

---

There is also a playground for this build and an npm module you can use via "typescript": "npm:@typescript-deploys/pr-build@4.5.0-pr-44619-4".;

[andrewbranch]

@xiaoxiangmoe that’s an option, but some people (I think reasonably) don't want to have two separate import statements for nearly every module, so we’re planning to add the specifier-level type modifier for ergonomics.

[andrewbranch]

Renamed to preserveValueImports

[xiaoxiangmoe]

import { type WriteFileOptions } from "fs";

Under --preserveValueImports, import "fs"; or import {} from 'fs'; or ;, which one should we compile it to?

[andrewbranch]

My plan was for that to emit import {} from "fs". I think that’s the most intuitive.

[robpalme]

import { type WriteFileOptions } from "fs";
My plan was for that to emit import {} from "fs". I think that’s the most intuitive.

That's definitely the desired behavior for "importsNotUsedAsValues": "preserve"

I assume the whole import would be elided in the case of "importsNotUsedAsValues": "remove" (though I really don't mind either way here).

[andrewbranch]

Yeah, my answer was for --preserveValueImports, but I agree with that as well @robpalme.

[robpalme]

Thank you for landing this feature in time for TypeScript 4.5! 🎉

I am super excited for the follow-on PR to introduce type-only import identifiers. Probably we would wait for that before enabling this feature, to avoid doubling up on import lines (that would occur via the addition of an import type line). IMO this all adds up to excellent progress towards explicitness and simplicity.

[nyngwang]

import { type WriteFileOptions } from "fs";

Under --preserveValueImports, import "fs"; or import {} from 'fs'; or ;, which one should we compile it to?

@xiaoxiangmoe Sorry for tagging, but I found your example might not be related in that it has nothing to do with the option/flag --preserveValueImports, which is all about value-having imports as clearly stated in OP. To conclude: An import that is used as a type was destined to be removed when
--preserveValueImports was not yet deprecated.

If you found my argument wrong, please let me know. Thanks for your reading.