12.2 Ambient Module Declarations

An AmbientModuleDeclaration declares a module. This type of declaration is permitted only at the top level in a source file that contributes to the global namespace (section 11.1). The StringLiteral must specify a top-level module name. Relative module names are not permitted.

  AmbientModuleDeclaration:   declare module StringLiteral {  DeclarationModule }

An ImportRequireDeclaration in an AmbientModuleDeclaration may reference other modules only through top-level module names. Relative module names are not permitted.

If an ambient module declaration includes an export assignment, it is an error for any of the declarations within the module to specify an export modifier. If an ambient module declaration contains no export assignment, entities declared in the module are exported regardless of whether their declarations include the optional export modifier.

Ambient modules are “open-ended” and ambient module declarations with the same string literal name contribute to a single module. For example, the following two declarations of a module ‘io’ might be located in separate source files.

declare module "io" {  
    export function readFile(filename: string): string;  
}
declare module "io" {  
    export function writeFile(filename: string, data: string): void;  
}

This has the same effect as a single combined declaration:

declare module "io" {  
    export function readFile(filename: string): string;  
    export function writeFile(filename: string, data: string): void;  
}