Allow passing a TypeReference aliasing a ModuleDeclaration as the argument to an ImportTypeNode

Search Terms

ImportTypeNode, TypeReference, argument

Problem

Consider this scenario:

File: foo.ts:

export type foo = typeof import("./bar");

File: bar.ts:

export type bar = number;

Let's say we're building a tool that can bundle and flatten declaration files, and instead of relying on the approach used by TypeScript's outFile feature where SourceFiles are inlined as ModuleDeclarations, it produces flat, easily consumable declarations. How would we go about bundling these two files?

Intuitively, we might think that we can turn it into the following:

declare module barNS {
  type bar = number;
}
export type foo = typeof barNS;

But we can't, that will instead trigger a Cannot use namespace 'barNS' as a type. diagnostic.
Instead, we can use an ImportEqualsDeclaration:

declare module barNS {
  type bar = number;
}
import foo = barNS;
export {foo};

Now, this worked since we could replace the TypeAliasDeclaration (type foo = ...) with the ImportEqualsDeclaration, given that they are both declarations. But things get tricky as soon as they aren't interchangeable. For example, let's say that foo.ts looked like this instead:

export type foo = () => typeof import("./bar");

How would we merge the two declaration files into one? Well, we can try:

declare module barNS {
  type bar = number;
}
import foo$ = barNS;

// Doesn't work, produces 'Cannot use namespace 'foo$' as a type'
export type foo = () => foo$;
export {foo};

We can't do it. The only workaround is to produce inline declarations of both modules, just like TypeScript's outFile mode would do it:

declare module "bar" {
    export type bar = number;
}
declare module "foo" {
    export type foo = () => typeof import("bar");
}

However, there are several declaration bundlers in existence that tries to work around this, one of which I am maintainer of, and I would like to propose a way forward here.

Suggestion

Today, the ImportTypeNode interface accepts a TypeNode for its argument property:

export interface ImportTypeNode extends NodeWithTypeArguments {
  // ...
  readonly argument: TypeNode;
  // ...
}

However, TypeScript always expects a StringLiteralType argument and will produce a diagnostic (1141): String literal expected if any other kind of TypeNode is provided.

I propose that this diagnostic is removed, and that it is allowed to pass a TypeReference as the argument property for an ImportTypeNode. When a TypeReference aliasing a ModuleDeclaration is provided, the resulting type is functionally equivalent to that of importing it from another SourceFile. With it, the following will be possible:

declare module barNS {
  type bar = number;
}
export type foo = () => typeof import(barNS);

This is also a safe feature to implement, given that it doesn't affect emit. It is also backwards compatible, given that passing anything else than a StringLiteralType to the argument of an ImportTypeNode currently produces an error diagnostic.

Use Cases

• Bundling/merging/flattening of declarations
• No current approaches exist that declaration bundlers can use to work around this

Checklist

My suggestion meets these guidelines:

• This wouldn't be a breaking change in existing TypeScript/JavaScript code
• This wouldn't change the runtime behavior of existing JavaScript code
• This could be implemented without emitting different JS based on the types of the expressions
• This isn't a runtime feature (e.g. library functionality, non-ECMAScript syntax with JavaScript output, etc.)
• This feature would agree with the rest of TypeScript's Design Goals.

Start with the ImportTypeNode interface and the handling of diagnostic 1141, then trace how ImportTypeNode arguments are checked and resolved. Done means a TypeReference aliasing a ModuleDeclaration is accepted and the declaration-bundling examples type-check without the namespace-as-type diagnostic.