Document namespace workaround for typing import * as x

[garthk]

Writing Declaration Files under "Function as an Module " doesn't mention the namespace required for ES6 imports to work, as documented in microsoft/TypeScript#5073 and marked By Design by @mhegazy.

TL;DR: you need the namespace in the typing below, else tsc will error out when you import * from 'foo':

Module '"foo"' resolves to a non-module entity and cannot be imported using this construct

declare module "foo" {
  function foo(): void;
  namespace foo {} // required for ES6: import * from "foo";
  export = foo;
}

[blakeembrey]

This would be a good thing to clarify in documentation because I see this hack too often. I'm not sure whether people actually read the issue or if I'm reading it wrong, but the comment literally says the fact this works is the bug.

That you can call the alias as a function in the second case, is the bug i would say.

[DanielRosenwasser]

Technically the interop layer between ES and CommonJS is in flux, so I'm not sure if we should be documenting this. The way that we and the CTC are leaning is that export = entities should have been default imports, but we'll see how this goes.

[blakeembrey]

@DanielRosenwasser Agreed, but guidance on it would be a good idea. Even if it says, "it's not recommended to use this as it's currently a hack and may become obsolete with future releases" would be a great idea. I currently see more than enough PRs trying to introduce this exact hack to support ES6 imports. Perhaps enabling these imports of export = entities should be moved behind a flag also, because I do believe there's an ES6 module audience that requires this hack (even though I've been denying these PRs in @types so far).

[DanielRosenwasser]

Fair enough - @garthk feel free to send a PR, but make sure it mentions that it's a workaround.

[garthk]

Are there other ways of solving the problem? Encouraging module authors to take a breaking change to up-end a Node tradition of exporting functions seems hair-raising. Offsetting that, it's only required for packages that export a function and stuff other parts of the API into properties on that function.

[blakeembrey]

@garthk Not sure what you're referring to breaking change. I think you misunderstand. You can and have always been able to import CommonJS modules using import x = require('x'). But that's on the import side, not the export side.

Correct if I mistook your post, but are you able to lay out the "problem" and also what "up-end a Node tradition" means?