Confusing documentation on namespaces/internal modules

[maxkoretskyi]

The official TS manual says the following:

It’s important to note that in TypeScript 1.5, the nomenclature has changed. “Internal modules” are now “namespaces”. “External modules” are now simply “modules”

Based on that quote, I was under impression that declare module is no longer used and should be replaced by declare namespace, however I still see module used in different packages. For example, when exploring node_modules\@types\node\index.d.ts I can see that both declare module and declare namespace is used:

declare namespace NodeJS {
    export var Console: {
        prototype: Console;
        new(stdout: WritableStream, stderr?: WritableStream): Console;
    }
...

declare module "buffer" {
    export var INSPECT_MAX_BYTES: number;
    var BuffType: typeof Buffer;
    var SlowBuffType: typeof SlowBuffer;
    export { BuffType as Buffer, SlowBuffType as SlowBuffer };
}

Is it simply a legacy code and declare module "buffer" can be replaced with declare namespace buffer, or there is a difference between them and I should use declare module in my code as well?

[mhegazy]

Pre-TS 1.5, the keyword module was used to refer to two different concepts, 1. modules (aka external modules), e.g. a node module, and 2. namespaces (aka internal modules), these are just named object literals.

the distinction was the name of the module declaration, which is a bit subtle. Declarations with quotes in the name are modules, otherwise they are namespace, so:

This is a module:

declare module "buffer" { ... }

Whereas this is a namespace

declare module buffer { ..}

This was confusing; so in TS 1.5 we have added a new keyword namespace to make it clear which is which.

for backward compatibility the old use of module are still allowed, but not recommended.

We recommend adding a tslint rule (no-internal-module) to force the use of namespace

[maxkoretskyi]

Thanks for the clarification!
So what's the use case for
declare module "buffer" { ... }
now that ES6 modules are supported?

[devdoomari]

@MaximusK those are for d.ts files (typescript definition files).
example:
custom-typings/buffer/buffer.d.ts

declare module 'buffer' { ... export default something }

somewhere.ts

import something from 'buffer'

[mhegazy]

Thanks for the clarification!
So what's the use case for
declare module "buffer" { ... }
now that ES6 modules are supported?

you can still define multiple modules in the same file. for instance, https://github.com/DefinitelyTyped/DefinitelyTyped/blob/master/node/index.d.ts

[maxkoretskyi]

@devdoomari , thanks, but if I have one module per file, as in your case custom-typings/buffer/buffer.d.ts, there is no need for declare module 'buffer' {export class A {}} as I can put all exports at the root of the file and it will work just fine with import something from 'buffer'.

@mhegazy , thanks, so basically it's usage is specific to putting multiple external modules exports in one declaration file, correct? Is there a compiler option that can do that?

[mhegazy]

@mhegazy , thanks, so basically it's usage is specific to putting multiple external modules exports in one declaration file, correct? Is there a compiler option that can do that?

if you are asking can the compiler generate a declaration file like so, the answer is yes, use --outFile with --module AMD or --module System and the .d.ts file will have multiple modules in a single .d.ts file like the .js file has several modules.

[maxkoretskyi]

Thanks a lot for you time. Appreciate you guys spending time answering support questions!