TypeScript声明文件中引用库类型如何避免全局变量污染？

Great question—this is a common pitfall when working with TypeScript type definitions that depend on other libraries without wanting to pollute the global scope. Let's break this down step by step:

Can you reference types from another .d.ts without introducing unwanted globals? #

Yes! The key is to use module-level imports instead of global <reference> directives. Here's why your initial approach caused issues:

• /// <reference types="node" /> in a non-module .d.ts file injects all of Node.js's global type definitions (like replacing the global setTimeout return type from number to Timer) into every project that uses @types/mocha. This clashes with projects like pjax-api that expect timer IDs to be number.

Instead, you can import the EventEmitter type directly as a module type, which keeps it scoped to your type definition file without leaking globals:

// In @types/mocha's runner definition file
import type { EventEmitter } from 'events';

export interface IRunner extends EventEmitter {
  // Your existing IRunner properties/methods here
}

By using import type (available in TypeScript 2.9+), you're only importing the type information, not any runtime code. Since the file now acts as a module (thanks to the import), Node.js's global types won't be injected into the consuming project's global scope.

Do the example type packages you mentioned have the same issue? #

It depends on how they're structured:

• Packages like @types/mocha@2.2.45 and @types/couchbase use global <reference types="node" /> in non-module files, so they do pollute the global scope and cause the same conflict you saw.
• Packages like @types/artillery use import * as events from 'events';—since this turns the file into a module, the Node.js types are only scoped to that module, so they don't leak globals. This is the correct approach.

Better solutions than your temporary fixes #

Your current workarounds are understandable, but there's a cleaner, maintainable way that aligns with TypeScript's best practices:

1. Use module-scoped type imports: As shown above, this keeps your type definitions DRY (no copying Node.js types) and doesn't require consumers to manually configure anything. The type package itself handles the dependency correctly.
2. Ensure your .d.ts file is a module: For older TypeScript versions, adding a dummy export {} at the bottom of the file will mark it as a module, preventing global <reference> directives from leaking into the consuming project's global scope. Though import type is preferable, this is a reliable fallback.

Why this works for Mocha's IRunner #

Mocha's Runner does inherit from NodeJS.EventEmitter, so it's correct to model that in the type definitions. By using module-scoped imports, you're accurately representing that inheritance without forcing Node.js's global types onto every project that uses @types/mocha—which is exactly what the pjax-api project needs to avoid the Timer vs number conflict.

内容的提问来源于stack exchange，提问作者Will Westrop