Using /// <reference lib="dom" /> in a .d.ts typescript declaration file has global effects

[pyBlob]

TypeScript Version: 3.5.3, 3.6.3

Search Terms:

• triple slash lib dom
• triple slash global

Code

arbitrary.d.ts

/// <reference lib="dom" />

index.ts

export let x: Element;

Expected behavior:
Executing npx tsc --noEmit --target esnext --lib esnext index.ts should produce a compile error because Element is not defined nor imported and lib dom is not set globally.

The documentation for triple slash directives states the following:
https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html

• For declaration file authors who rely on built-in types, e.g. DOM APIs or built-in JS run-time constructors like Symbol or Iterable, triple-slash-reference lib directives are recommended. Previously these .d.ts files had to add forward/duplicate declarations of such types.
  used in e.g. https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/types/superagent/index.d.ts

Actual behavior:
It just compiles.

Related Issues:

• Placeholder Type Declarations #31894
• Don't let the declaration file break compilation #32908 (adding skipLibChecks does not solve this problem, and should not be the right solution)

[RyanCavanaugh]

This is what a lib reference does.

[pyBlob]

Ah ok, so lib references also have this behaviour for all files in the compilation, not only the d.ts files. After reading the documentation another time I found the description: For example, adding /// <reference lib="es2017.string" /> to one of the files in a compilation is equivalent to compiling with --lib es2017.string..

We have found this is an issue, because we had a node typescript project that uses superagent/supertest. During refactoring an import to our own "Element" method got dropped, which however didn't cause the compilation to fail. Instead it caused a seperate project to fail compilation, because types didn't match. (Local testcases would have probably caught this issue).

Is there a way to make sure that no package may change our compilation settings? (other than manually checking every file and after every update)
Is there a way to have local lib references, that are scoped to the file they are used in?

[pyBlob]

Do you think that splitting @types packages like the one for superagent into multiple packages depending on intended usage environment is a viable option?

[typescript-bot]

This issue has been marked 'Working as Intended' and has seen no recent activity. It has been automatically closed for house-keeping purposes.

[aleclarson]

@RyanCavanaugh Should type directives be confined to the project they're imported by?

For example, let's say I have a __stories__ folder nested in my React Native app's src directory, Storybook happens to depend on @types/node, and I have a tsconfig.story.json that only includes **/__stories__ modules.

The problem is that Storybook uses a type directive, and it leaks into my React Native modules, despite them never importing Storybook. I've made sure the tsconfig.native.json (used by React Native modules) excludes **/__stories__ modules, yet @types/node leaks in anyway.

[carlpaten]

Is there a workaround for this from the point of view of the library user? type-fest and cross-fetch both include triple-slash references, and they both appear several times in our transitive dependencies. I'm happy to work with them to solve this problem, but it will take a lot of time and effort for the solution to trickle through the ecosystem. Is there something we can do in the meantime?

[aleclarson]

@LilRed There's no workaround until the strictEnvironment proposal or something similar is implemented.